The intended use-case for BaseDirectories is to query the paths of user-invisible standard directories that have been defined according to the conventions of the operating system the library is running on.
If you want to compute the location of cache, config or data folders for your own application or project, use ProjectDirectories instead.
The intended use-case for UserDirectories is to query the paths of user-facing standard directories that have been defined according to the conventions of the operating system the library is running on.
The intended use-case for ProjectDirectories is to compute the location of cache, config or data folders for your own application or project, which are derived from the standard directories.
| Type | Purpose | XDG Environment Variable | Linux / BSD | MacOS |
|---|---|---|---|---|
| Base | home | HOME | $HOME | $HOME |
| Base | cache | XDG_CACHE_HOME | $XDG_CACHE_HOME or $HOME/.cache | $HOME/Library/Caches |
| Base | config | XDG_CONFIG_HOME | $XDG_CONFIG_HOME or $HOME/.config | $HOME/Library/Application Support |
| Base | data | XDG_DATA_HOME | $XDG_DATA_HOME or $HOME/.local/share | $HOME/Library/Application Support |
| Base | dataLocal | XDG_DATA_HOME | $XDG_DATA_HOME or $HOME/.local/share | $HOME/Library/Application Support |
| Base | executable | XDG_BIN_HOME | $XDG_BIN_HOME or $HOME/.local/bin | null |
| Base | preference | XDG_CONFIG_HOME | $XDG_CONFIG_HOME or $HOME/.config | $HOME/Library/Preferences |
| Base | runtime | XDG_RUNTIME_DIR | $XDG_RUNTIME_DIR or null | null |
| User | audio | XDG_MUSIC_DIR | $XDG_MUSIC_DIR | $HOME/Music |
| User | desktop | XDG_DESKTOP_DIR | $XDG_DESKTOP_DIR | $HOME/Desktop |
| User | document | XDG_DOCUMENTS_DIR | $XDG_DOCUMENTS_DIR | $HOME/Documents |
| User | download | XDG_DOWNLOAD_DIR | $XDG_DOWNLOAD_DIR | $HOME/Downloads |
| User | font | XDG_DATA_HOME | $XDG_DATA_HOME/fonts or $HOME/.local/share/fonts | $HOME/Library/Fonts |
| User | picture | XDG_PICTURES_DIR | $XDG_PICTURES_DIR | $HOME/Pictures |
| User | public | XDG_PUBLICSHARE_DIR | $XDG_PUBLICSHARE_DIR | $HOME/Public |
| User | template | XDG_TEMPLATES_DIR | $XDG_TEMPLATES_DIR | null |
| User | video | XDG_VIDEOS_DIR | $XDG_VIDEOS_DIR | $HOME/Movies |
| Project | cache | XDG_CACHE_HOME/<project_path> | $XDG_CACHE_HOME or $HOME/.cache/<project_path> | $HOME/Library/Caches/<project_path> |
| Project | config | XDG_CONFIG_HOME/<project_path> | $XDG_CONFIG_HOME or $HOME/.config/<project_path> | $HOME/Library/Preferences/<project_path> |
| Project | data | XDG_CONFIG_HOME/<project_path> | $XDG_CONFIG_HOME or $HOME/.config/<project_path> | $HOME/Library/Application Support/<project_path> |
| Project | dataLocal | XDG_DATA_HOME/<project_path> | $XDG_DATA_HOME or $HOME/.local/share/<project_path> | $HOME/Library/Application Support/<project_path> |
| Project | preference | XDG_DATA_HOME/<project_path> | $XDG_DATA_HOME or $HOME/.local/share/<project_path> | $HOME/Library/Application Support/<project_path> |
| Project | runtime | XDG_RUNTIME_DIR/<project_path> | $XDG_RUNTIME_DIR/<project_path> | null |
I just came across this when searching for something else & it's just not a good idea to equate those paths on Linux & macOS.
First of all, the
XDG_*variables are not defined by default on macOS. If a user decides to define them manually, then the overwhelming majority of them would define them the same as that on Linux. The reason for this is that locations such as~/.config,~/.cache, &~/.localare already used by most of the Terminal/CLI tools on macOS. Only users who work a lot with CLI tools are gonna bother with setting those variables & they're gonna choose the same locations as that on Linux.Not to mention that that folder is already used by a lot of GUI apps & typing out
~/Library/Application Supportor something is really tedious.The only CLI tools which use those weird locations on macOS are the ones that use the directories-jvm or the directories-rs packages, which have sadly become really popular.
I think a better name for this would be Standard Directories for Linux & Mac for GUI apps. For CLI tools, you're much better off just following the good old XDG spec.