A library to locate common directories using platform-specific conventions.
This library follows platform-specific conventions to locate common directories.
For example, the correct directory to use for application configuration files
might be $HOME/.config/my-app on Linux,
$HOME/Library/Application Support/My App on Macos, and
%APPDATA%\My App\config on Windows.
To use:
var appDirs = getAppDirs(application: 'FooBar App');
// Use this directory for general application configuration files.
var configDir = appDirs.config;
...
// Use this directory for cached information.
var cacheDir = appDirs.cache;
...See also our API docs.
For MacOS defaults, we follow Apple's
- Standard Directories
docs. This generally puts files in subdirectories of
$HOME/Library, which is appropriate for most Mac apps.
API clients can opt into a separate set of file location convetions for Macos.
This is done via the preferUnixConventions flag:
var appDirs = getAppDirs(
application: 'FooBar App',
preferUnixConventions: true,
);This will opt that tool into using Unix style directory conventions - for
example, putting config files into $HOME/.config/foobar-app. While not the
Macos standard file locations, this could better match user expectations for
things like command-line tools.
On Unix OSes, we follow the
XDG Base Directory Specification.
This is generally creating directories under the user's $HOME directory, but
respecting various $XDG_* environment variable overrides.
On Windows, we follow the standard Windows directory structure convention (docuented here and elsewhere).
This is the table of directories returned for Directories.baseDirs.
AppDirs - the recommended API for people to use - builds on top of this using
information like the application name, qualifier (org, com, ...) and
organization name.
| Property | Linux | Mac | Windows |
|---|---|---|---|
| home | $HOME |
$HOME |
%USERPROFILE% |
| cache | $XDG_CACHE_HOME or $HOME/.cache |
$HOME/Library/Caches |
%LOCALAPPDATA% |
| config | $XDG_CONFIG_HOME or $HOME/.config |
$HOME/Library/Application Support |
%APPDATA% |
| data | $XDG_DATA_HOME or $HOME/.local/share |
$HOME/Library/Application Support |
%APPDATA% |
| dataLocal | see data | see data | %LOCALAPPDATA% |
| preference | see config | $HOME/Library/Preferences |
see config |
| state | $XDG_STATE_HOME or $HOME/.local/state |
null |
null |
Specifications and documentation:
- https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
- developer.apple.com/library/archive/documentation/FileManagement
- https://pureinfotech.com/list-environment-variables-windows-10/
Similar libraries for other platforms:
For information about our publishing automation and release process, see https://github.com/dart-lang/ecosystem/wiki/Publishing-automation.