Skip to content
Snippets Groups Projects
README.md 25.27 KiB

xdg logo

Go implementation of the XDG Base Directory Specification and XDG user directories.

Tests status Code coverage pkg.go.dev documentation MIT license
Go report card Awesome Go GitHub contributors GitHub open issues Buy me a coffee

Provides an implementation of the XDG Base Directory Specification. The specification defines a set of standard paths for storing application files, including data and configuration files. For portability and flexibility reasons, applications should use the XDG defined locations instead of hardcoding paths.

The package also includes the locations of well known user directories, support for the non-standard XDG_BIN_HOME directory, as well as other common directories such as fonts and applications.

The current implementation supports most flavors of Unix, Windows, macOS and Plan 9.
On Windows, where XDG environment variables are not usually set, the package uses Known Folders as defaults. Therefore, appropriate locations are used for common folders which may have been redirected.

See usage examples below. Full documentation can be found at https://pkg.go.dev/github.com/adrg/xdg.

Installation

go get github.com/adrg/xdg

Default locations

The package defines sensible defaults for XDG variables which are empty or not present in the environment.

  • On Unix-like operating systems, XDG environment variables are typically defined. Appropriate default locations are used for the environment variables which are not set.
  • On Windows, XDG environment variables are usually not set. If that is the case, the package relies on the appropriate Known Folders. Sensible fallback locations are used for the folders which are not set.

XDG Base Directory

Unix-like operating systems

Unix

macOS

Plan 9

XDG_DATA_HOME ~/.local/share ~/Library/Application Support $home/lib
XDG_DATA_DIRS /usr/local/share
/usr/share
/Library/Application Support~/.local/share /lib
XDG_CONFIG_HOME ~/.config ~/Library/Application Support $home/lib
XDG_CONFIG_DIRS /etc/xdg ~/Library/Preferences
/Library/Application Support
/Library/Preferences
~/.config
/lib
XDG_STATE_HOME ~/.local/state ~/Library/Application Support $home/lib/state
XDG_CACHE_HOME ~/.cache ~/Library/Caches $home/lib/cache
XDG_RUNTIME_DIR /run/user/$UID ~/Library/Application Support /tmp
XDG_BIN_HOME ~/.local/bin ~/.local/bin $home/bin
Microsoft Windows

Known Folder(s)

Fallback(s)

XDG_DATA_HOME LocalAppData %LOCALAPPDATA%
XDG_DATA_DIRS RoamingAppData
ProgramData
%APPADATA%
%ProgramData%
XDG_CONFIG_HOME LocalAppData %LOCALAPPDATA%
XDG_CONFIG_DIRS ProgramData
RoamingAppData
%ProgramData%
%APPDATA%
XDG_STATE_HOME LocalAppData %LOCALAPPDATA%
XDG_CACHE_HOME LocalAppData\cache %LOCALAPPDATA%\cache
XDG_RUNTIME_DIR LocalAppData %LOCALAPPDATA%
XDG_BIN_HOME UserProgramFiles %LOCALAPPDATA%\Programs

XDG user directories

XDG user directories environment variables are usually not set on most operating systems. However, if they are present in the environment, they take precedence. Appropriate fallback locations are used for the environment variables which are not set.

  • On Unix-like operating systems (except macOS and Plan 9), the package reads the user-dirs.dirs config file.
  • On Windows, the package uses the appropriate Known Folders.

Lastly, default locations are used for any user directories which are not set, as shown in the following tables.

Unix-like operating systems

Unix

macOS

Plan 9

XDG_DESKTOP_DIR ~/Desktop ~/Desktop $home/desktop
XDG_DOWNLOAD_DIR ~/Downloads ~/Downloads $home/downloads
XDG_DOCUMENTS_DIR ~/Documents ~/Documents $home/documents
XDG_MUSIC_DIR ~/Music ~/Music $home/music
XDG_PICTURES_DIR ~/Pictures ~/Pictures $home/pictures
XDG_VIDEOS_DIR ~/Videos ~/Movies $home/videos
XDG_TEMPLATES_DIR ~/Templates ~/Templates $home/templates
XDG_PUBLICSHARE_DIR ~/Public ~/Public $home/public