Set and Safely Test XDG User Directories with xdg-user-dirs-update

You will finish with a working set of XDG user directories, a way to change one directory without guessing at the file format, and a safe test method that does not touch your real home directory. The examples use xdg-user-dirs 0.18-1build1, installed on Ubuntu 24.04 in this environment.

Allow about fifteen minutes. You need a shell and a writable home directory. The normal update changes per-user configuration and can create directories, so do not run it casually on an account whose layout you have not checked. No example here needs sudo; system-wide defaults and policy are separate work.

1. Check the installed command and defaults

Start with read-only checks. The installed program has no useful --version option, so identify the binary and package instead:

$ command -v xdg-user-dirs-update
/usr/bin/xdg-user-dirs-update
$ dpkg-query -W -f='${Package} ${Version}\n' xdg-user-dirs
xdg-user-dirs 0.18-1build1
$ xdg-user-dirs-update --help
Usage: xdg-user-dirs-update [--force] [--dummy-output <path>] [--set DIR path]

On another distribution, use its package query tool. The option set is the part that matters here: --force, --dummy-output and --set. An invalid --version is not evidence that the utility is missing.

Checkpoint: inspect the defaults before changing anything:

$ sed -n '1,120p' /etc/xdg/user-dirs.defaults
DESKTOP=Desktop
DOWNLOAD=Downloads
TEMPLATES=Templates
PUBLICSHARE=Public
DOCUMENTS=Documents
MUSIC=Music
PICTURES=Pictures
VIDEOS=Videos

The defaults file contains relative names below the home directory. It is read through XDG_CONFIG_DIRS, which defaults to /etc/xdg. It is not the file you normally edit to set one user's directory.

2. Understand the three files

Per-user configuration lives below XDG_CONFIG_HOME, which defaults to $HOME/.config. The main file is user-dirs.dirs. It uses shell-compatible assignments such as:

XDG_DOWNLOAD_DIR="$HOME/Downloads"
XDG_DOCUMENTS_DIR="$HOME/Documents"

The recognised names are DESKTOP, DOWNLOAD, TEMPLATES, PUBLICSHARE, DOCUMENTS, MUSIC, PICTURES and VIDEOS. Values must be either $HOME/Path or an absolute path. The format is designed to be sourced by shell scripts, so keep it as generated and do not add arbitrary shell commands.

user-dirs.conf controls behaviour. A system copy is normally /etc/xdg/user-dirs.conf; a per-user copy at $XDG_CONFIG_HOME/user-dirs.conf overrides it. The recognised settings are enabled=True or False, and filename_encoding=UTF-8, another encoding, or locale. With enabled=False, the updater will not change the XDG configuration.

On the first normal run, user-dirs.locale records the locale used for translation. Desktop tools can use that marker when a locale change makes directory names need migration.

3. Preview a fresh configuration without changing your home

Use --dummy-output when you want to see generated configuration or test a script. It writes to the path you provide and does not create directories. This is an ordinary, unprivileged command:

$ mkdir -p /tmp/xdg-preview
$ HOME=/tmp/xdg-preview/home \
  XDG_CONFIG_HOME=/tmp/xdg-preview/config \
  xdg-user-dirs-update --dummy-output /tmp/xdg-preview/user-dirs.dirs
$ sed -n '1,40p' /tmp/xdg-preview/user-dirs.dirs
XDG_DESKTOP_DIR="$HOME/Desktop"
XDG_DOWNLOAD_DIR="$HOME/Downloads"
XDG_TEMPLATES_DIR="$HOME/Templates"

The output includes the complete generated file, including comments. The exact translated names depend on your locale and defaults. Because this mode does not create directories, it is a useful checkpoint before an automated login job or image build.

4. Create the standard set for one user

When the defaults are acceptable, run the updater as the target user:

$ xdg-user-dirs-update
$ sed -n '1,40p' "$HOME/.config/user-dirs.dirs"
XDG_DESKTOP_DIR="$HOME/Desktop"
XDG_DOWNLOAD_DIR="$HOME/Downloads"
XDG_TEMPLATES_DIR="$HOME/Templates"

If no configuration exists, the command creates one from system defaults, with a fallback to old non-translated names such as Desktop, Templates and Public when those directories already exist. It also creates missing standard directories. Check the result rather than assuming every name is present:

$ while IFS= read -r line; do
>   case "$line" in XDG_*_DIR=*) printf '%s\n' "$line";; esac
> done < "$HOME/.config/user-dirs.dirs"
$ test -d "$HOME/Downloads" && echo 'Downloads exists'
Downloads exists

Do not run this as root to repair a user's configuration. Root would use a different home and can leave files owned by the wrong account.

5. Change one directory with --set

Use an absolute path for the directory you want to assign. This example moves the download target to an existing directory named Incoming:

$ mkdir -p "$HOME/Incoming"
$ xdg-user-dirs-update --set DOWNLOAD "$HOME/Incoming"
$ grep '^XDG_DOWNLOAD_DIR=' "$HOME/.config/user-dirs.dirs"
XDG_DOWNLOAD_DIR="$HOME/Incoming"

The name must be one of the eight recognised names, and the path must be absolute. The --set operation updates the configuration; create the destination yourself if you need it to exist. Applications may read the file only when they start, so restart an affected application or session if it keeps using the old location.

This changes state. To undo this exact example, point the entry back at the default and verify it:

$ xdg-user-dirs-update --set DOWNLOAD "$HOME/Downloads"
$ grep '^XDG_DOWNLOAD_DIR=' "$HOME/.config/user-dirs.dirs"
XDG_DOWNLOAD_DIR="$HOME/Downloads"

6. Handle missing directories and force carefully

During an ordinary update, configured directories that no longer exist can be reset to the home directory because removing a directory often means the user no longer wants it. Read the file after an update if a path suddenly looks like $HOME. Recreate the intended directory, then assign it explicitly with --set:

$ mkdir -p "$HOME/Projects/Downloads"
$ xdg-user-dirs-update --set DOWNLOAD "$HOME/Projects/Downloads"
$ grep '^XDG_DOWNLOAD_DIR=' "$HOME/.config/user-dirs.dirs"
XDG_DOWNLOAD_DIR="$HOME/Projects/Downloads"

Do not use --force as a general repair command. In this version it performs a full reset, recreates the locale marker, avoids resetting non-existing directories to $HOME, and does not use backwards-compatible non-translated names. It can therefore change several entries at once. Back up the configuration first if you must use it:

$ cp --preserve=mode,timestamps "$HOME/.config/user-dirs.dirs" \
    "$HOME/.config/user-dirs.dirs.before-force"
$ xdg-user-dirs-update --force
$ diff -u "$HOME/.config/user-dirs.dirs.before-force" \
    "$HOME/.config/user-dirs.dirs" || true

To recover the previous mappings, restore that backup and remove the newly created locale marker only if you deliberately want to return to the earlier state. Do not delete a directory just because its mapping changed; the updater does not provide an undo for filesystem contents.