XDG

X Desktop Group

What is XDG

The XDG (X Desktop Group) specifications are a set of standards aimed at providing consistency across Linux desktop environments. They help define standard locations for user files, directories, and application behavior, ensuring interoperability between different desktop environments and applications.

The most well-known XDG specification is the XDG Base Directory Specification, which standardizes locations for configuration files, data files, and caches. This includes directories like ~/.config for configuration files, ~/.local/share for user data, and ~/.cache for temporary files. It helps applications store data in predictable locations, improving user experience and system cleanliness.

Another important XDG standard is the XDG Desktop Entry Specification, which defines how applications should describe themselves to the desktop environment. This includes .desktop files, which provide metadata like application name, icon, and command for launching, allowing desktop environments to present applications consistently. Overall, the XDG specs contribute to a unified and organized Linux desktop ecosystem.

The primary integration of the XDG specifications is designed for graphical user interfaces across different desktop environments

How to install xdg utils

There are many suites of program but the main one is xdg-utils
sudo apt install xdg-utils

Contains the programs

  • xdg-desktop-menu
    • Install desktop menu items
  • xdg-desktop-icon
    • Install icons on the user’s desktop
  • xdg-email
    • Compose a new email in the user’s preferred email client, potentially with subject and other info filled in
  • xdg-icon-resource
    • Install icon resources
  • xdg-mime
    • Query and install MIME types and associations
  • xdg-open
    • Open a URI in the user’s preferred application that handles the respective URI or file type
  • xdg-screensaver
    • Enable, disable, or suspend the screensaver
  • xdg-settings
    • Get or set the default web browser and URI handlers

How to install xdg-user-dirs

sudo apt install xdg-user-dirs

Contains the programs

  • xdg-user-dirs-update
    • Updates the user directories based on the values in user-dirs.dirs
  • xdg-user-dirs-gtk-update
    • Updates the directories using a graphical interface (if supported by the desktop environment)

xdg-utils

xdg-mime

To view all MIME types you need to go directory
/usr/share/mime

They are typically represented as folder/file names following a hierarchical structure, e.i
/usr/share/mime/image/png.xml
then the mime type will be
image/png

Common Mime types are

Text Types

  • text/plain :Plain text files (e.g., .txt)
  • text/html :HTML files (e.g., .html, .htm)
  • text/css :Cascading Style Sheets (e.g., .css)
  • text/javascript : JavaScript files (e.g., .js)
  • text/xml : XML files (e.g., .xml)
  • text/csv : Comma-separated values files (e.g., .csv)

Image Types:

  • image/jpeg: JPEG images (e.g., .jpg, .jpeg)
  • image/png: PNG images (e.g., .png)
  • image/gif: GIF images (e.g., .gif)
  • image/webp: WebP images (e.g., .webp)
  • image/svg+xml: Scalable Vector Graphics (SVG) (e.g., .svg)
  • image/bmp: BMP images (e.g., .bmp)
  • image/tiff: TIFF images (e.g., .tiff, .tif)

Audio Types:

  • audio/mpeg: MP3 audio (e.g., .mp3)
  • audio/wav: WAV audio (e.g., .wav)
  • audio/ogg: Ogg Vorbis audio (e.g., .ogg)
  • audio/webm: WebM audio (e.g., .webm)
  • audio/flac: FLAC audio (e.g., .flac)

Video Types:

  • video/mp4: MP4 video (e.g., .mp4)
  • video/webm: WebM video (e.g., .webm)
  • video/ogg: Ogg video (e.g., .ogv)
  • video/avi: AVI video (e.g., .avi)
  • video/mpeg: MPEG video (e.g., .mpg, .mpeg)

Application Types:

  • application/json: JSON files (e.g., .json)
  • application/xml: XML files (e.g., .xml)
  • application/pdf: PDF documents (e.g., .pdf)
  • application/zip: ZIP archive files (e.g., .zip)
  • application/gzip: GZIP compressed files (e.g., .gz)
  • application/x-tar: TAR archive files (e.g., .tar)
  • application/x-rar-compressed: RAR archive files (e.g., .rar)
  • application/msword: Microsoft Word documents (e.g., .doc)
  • application/vnd.ms-excel: Microsoft Excel files (e.g., .xls)
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document: Microsoft Word (OpenXML) (e.g., .docx)

Font Types:

  • font/woff: Web Open Font Format (e.g., .woff)
  • font/woff2: Web Open Font Format 2 (e.g., .woff2)
  • font/ttf: TrueType font (e.g., .ttf)
  • font/otf: OpenType font (e.g., .otf)

Other Types:

  • application/octet-stream: Binary data (generic fallback MIME type)
  • application/x-www-form-urlencoded: URL-encoded form data (e.g., when submitting web forms)
  • application/x-shockwave-flash: Flash content (e.g., .swf)

Applications

When using the xdg-mime these commands/changes will be saved in the file ~/.config/mimeapps.list. It actually possible to change this file manually but not recommended. Use the tool xdg-mime and your life will be simpler. You could make the same change system-wide in the file /usr/share/applications/mimeapps.list
Note 1: The associated *.desktop file for the app MUST be present
Note 2: Locate desktop files(system-wide) with command sudo find /usr/share/applications/ -name "*.desktop"
Note 3: Locate desktop files(user home directory) with command find ~/.local/share/applications/ -name "*.desktop"

Check default application for a MIME type
xdg-mime query default "mime-type"

Set default application for a MIME type
xdg-mime default "application.desktop" "mime-type"
e.i set php files to geany
xdg-mime default geany.desktop application/x-php

Files

Check MIME type of a file
xdg-mime query filetype "filename"

Check matching mime-type of a file
xdg-mime test "mime-type" "filename"
e.i if the file country.php is a php file
xdg-mime query filetype country.php application/x-php

Example of file ~/.config/mimeapps.list

Execute the file with preferred application

xdg-open "filename"

xdg-settings

xdg-settings primarily provides get and set functionality for managing desktop environment preferences

Works with a set or a get property
xdg-settings get "property"
xdg-settings set "property"

List all available property on the computer system
xdg-settings --list

Note:The properties varies depending of desktop environments and also which window environment
And again these commands modifies the ~/.config/mimeapps.list

xdg-email

This util is quite limited in use. Its primary function is to pre-fill the composes email in the user preferred email client.

  • Open the default email client
  • Pre-fill the subject, body, and attachment
  • Fill in the recipient email address

xdg-email --subject "Meeting Reminder" --body "Just a reminder about our meeting tomorrow." --attach "/path/to/file.pdf" user@example.com

xdg-screensaver

This util is also quite limited in use. Its primary function is to activate/deactivate/lock and so on. Primary for desktop environments. Se man pages for more info
man xdg-screensaver

xdg-desktop-icon

.desktop file management

Command line tool for (un)installing icons to the desktop. install, remove, or update .desktop files on your desktop. It manages shortcuts for applications, placing them on the user’s desktop
Primarily involves the user’s home folder

  • Install: Moves a .desktop file to the desktop.
  • Remove: Deletes a .desktop file from the desktop.
  • Update: Refreshes or changes the .desktop file on the desktop.

It doesn’t modify system-wide application menus! Desktop folder in your user directory, typically located at ~/Desktop. This is where icons for applications (shortcuts) are placed in graphical desktop environments.

In order to understand icon you need to understand the structure and how its stored under linux
Icons are stored
Systemwide
/usr/share/icons/

User-specific icon themes
~/.local/share/icons/

When you set the property
Icon=gvim in a .desktop
it actually look recursively in the previous folder for a file names like

    • /usr/share/icons/Adwaita/16x16/apps/gvim.png
    • /usr/share/icons/Adwaita/22x22/apps/gvim.png
    • /usr/share/icons/Adwaita/32x32/apps/gvim.png
    • /usr/share/icons/Adwaita/48x48/apps/gvim.png
    • /usr/share/icons/Adwaita/64x64/apps/gvim.png
    • /usr/share/icons/Adwaita/128x128/apps/gvim.png

The suffix can also be some other like svg
Note:It also possible to specify a custom file path to the icon Icon=/path/to/custom/gvim-icon.png

Install a .desktop file on the desktop:
xdg-desktop-icon install /path/to/application.desktop

Uninstall (remove) .desktop file from the desktop:
xdg-desktop-icon uninstall /path/to/application.desktop

xdg-icon-resource

icon management

Manages icons within icon themes on the system

Command-line tool that is used to

  • install
  • remove
  • query icons

for desktop applications, particularly for icon themes. It interacts with icon themes on Linux systems.

Installs an icon into the system’s icon theme.
xdg-icon-resource install --size 48 /path/to/icon.png icon-name
Note:Adds icons to the system’s icon theme, usually in /usr/share/icons/ or ~/.local/share/icons/

Removes an icon from the icon theme.
xdg-icon-resource uninstall --size 48 icon-name

Forces an update of the icon theme cache, ensuring that any new or changed icons are recognized by the system.
xdg-icon-resource forceupdate

xdg-desktop-menu

Deals with installing .desktop files into the application menu system, which is what you see when you open your application launcher

I will return when the documentation will be better

xdg-user-dirs

xdg-user-dirs-update

There are 2 ways of actually using the xdg-user-dirs-update to create the files
~/.config/user-dirs.locale
~/.config/user-dirs.dirs

    • If both file do NOT exist run xdg-user-dirs-update. The content will not be accurate and you will need to run the command again after you modified these files
    • Create both files manually(the approach i will cover here here)

The command
xdg-user-dirs-update
updates the standard user directories (like Documents, Downloads, etc.) based on the locale and settings in
~/.config/user-dirs.locale
It renames the directories to their localized names, for example, “Documents” becomes “Dokument” if you’re using the Swedish locale.

Set up the locale file

1. Make sure that the file ~/.config/user-dirs.locale exist
otherwise
nano ~/.config/user-dirs.locale
Note:Important not to use sudo or be root here

2. Add the desired locale to the file nano ~/.config/user-dirs.locale
sv_SE.utf8
Note 1:You can only specify one locale
Note 2:The locale must be one of the locales listed in locale -a

Set up the file~/.config/user-dirs.dirs

One thing to understand that the values inside this file is NOT environmental variables. This file is used by xdg-user-dirs tool to read the values in this file
Note 1:Get the current set XDG download folder with xdg-user-dir DOWNLOAD
Note 2:Get the current set XDG music folder with xdg-user-dir MUSIC

Update user directories

xdg-user-dirs-update
Note 1:Does not erase existing directories or their contents within ONLY remanes them to match the locale settings
Note 2:Creates missing directories based on the new locale

ALWAYS run
xdg-user-dirs-update
after you

  • Modifies the file
  • Modifies the file

~/.config/user-dirs.locale
~/.config/user-dirs.dirs

xdg-user-dir

xdg-user-dir allows you to query the correct user directory paths as configured. Standard directories for user files and directories (like Documents, Desktop, Downloads

How It Works:

  • /etc/xdg/user-dirs.conf (systemwide) fallback
  • ~/.config/user-dirs.dirs (local config) – Takes precedence over systemwide
  • Uses Locale and Preferences
    • For local use only ~/.config/user-dirs.locale
  • Outputs Paths
    • xdg-user-dir DESKTOP
    • xdg-user-dir DOWNLOAD
    • xdg-user-dir TEMPLATES
    • xdg-user-dir PUBLICSHARE
    • xdg-user-dir DOCUMENTS
    • xdg-user-dir MUSIC
    • xdg-user-dir PICTURES
    • xdg-user-dir VIDEOS

It also possible to create “custom” directories here but you need to follow some naming convention here

    1. add the configuration variable with naming convention XDG_ACUSTOMNAMEHERE_DIR, in file ~/.config/user-dirs.dirs
      • e.i XDG_SPORT_DIR=”$HOME/Sport”
    2. Create the Custom Directory
      • mkdir -p $HOME/Sport
    3. Query the Custom Directory
      • xdg-user-dir SPORT