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

xdg-user-dirs-update can quietly reset a deleted directory's mapping back to home on its next run. That is exactly the kind of surprise this guide tries to head off. It covers building a working set of XDG user directories, changing one directory without guessing the file format, and a safe test method that leaves your real home directory alone. Examples use xdg-user-dirs 0.18-1build1, installed on Ubuntu 24.04.

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 what matters here: --force, --dummy-output and --set. An invalid --version is not evidence the utility is missing.

$ 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 holds relative names below the home directory. It is read through XDG_CONFIG_DIRS, which defaults to /etc/xdg, and it is not the file you normally edit to set one user's directory.

2. Understand the three files

user-dirs.dirs holds per-user configuration below XDG_CONFIG_HOME, which defaults to $HOME/.config. 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, and values must be either $HOME/Path or an absolute path. The format is meant to be sourced by shell scripts, so keep it as generated and never add arbitrary shell commands.

• user-dirs.conf controls behaviour. A system copy is normally /etc/xdg/user-dirs.conf, and 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 touch the XDG configuration.
• user-dirs.locale records the locale used for translation on the first normal run. Desktop tools use that marker when a locale change means directory names need migrating.

3. Preview a fresh configuration without changing your home

Use --dummy-output to see generated configuration or test a script. It writes to the path you give it and creates no directories, so it 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 is the complete generated file, comments included. The exact translated names depend on your locale and defaults. Because this mode creates nothing, 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 builds one from system defaults, falling back 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

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. --set only updates the configuration; create the destination yourself if it needs to exist. Applications may only read the file at startup, so restart an affected application or session if it keeps using the old location.

$ 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, on the theory that a removed directory 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"

$ 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