appdirs

package module
v0.0.0-...-85de447 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 24, 2026 License: MIT Imports: 6 Imported by: 3

README

appdirs

Go Reference CI

This is a port of the excellent python module named the same, which can be found here appdirs (now deprecated and replaced by platformdirs).

The original port was written by wessie this is a maintained fork of that project.

The Problem

When writing desktop application, finding the right location to store user data and configuration varies per platform. Even for single-platform apps, there may by plenty of nuances in figuring out the right location.

For example, if running on macOS, you should use

~/Library/Application Support/<AppName>

If on Windows (at least English Win) that should be::

C:\Documents and Settings\<User>\Application Data\Local Settings\<AppAuthor>\<AppName>

or possibly::

C:\Documents and Settings\<User>\Application Data\<AppAuthor>\<AppName>

for roaming profiles but that is another story.

On Linux (and other Unices), according to the XDG Basedir Spec, it should be

~/.local/share/<AppName>

appdirs to the rescue

This library provides a simple to use API to get the appropriate storage directories no matter the platform and what you want to store.

Documentation

Overview

A port of the excellent python module `platformdirs`. See https://github.com/platformdirs/platformdirs for the python version.

This is a port of a python module used for finding what directory you 'should' be using for saving your application data such as configuration, cache files or other files.

The location of these directories is often hard to get right. The original python module set out to change this into a simple API that returns you the exact directory you need. This is a port of it to Go.

Depending on platform, this package exports a broad set of functions that return standard system directories for application data, config, cache, logs, state, runtime files, media folders, binaries, and application shortcuts. It also exposes one helper struct type that combines these functions into methods for fewer arguments in your code.

Each function defined accepts a number of arguments, each argument is optional and can be left to the types default value if omitted. Often the function will ignore arguments if the name given is empty.

Passing in all default values into any of the functions will return you the base directory without any of the arguments appended to it.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func SiteApplicationsDir 

func SiteApplicationsDir() string

SiteApplicationsDir returns the path to the shared applications directory.

Examples of return values: 

Mac OS X: /Applications
Unix: /usr/local/share/applications
Windows: C:\ProgramData\Microsoft\Windows\Start Menu\Programs

func SiteBinDir 

func SiteBinDir() string

SiteBinDir returns the path to the shared binary directory.

Examples of return values: 

Mac OS X: /usr/local/bin
Unix: /usr/local/bin
Windows: C:\ProgramData\bin

func SiteCacheDir 

func SiteCacheDir(name, author, version string, opinion bool) string

SiteCacheDir returns the full path to the user-shared cache directory.

The opinion argument will append "Cache" to the base directory if set to true on platforms that follow that convention (e.g. Windows).

Examples of return values: 

Mac OS X: /Library/Caches/<AppName>
Unix: /var/cache/<AppName>
Windows: C:\ProgramData\<AppAuthor>\<AppName>\Cache

func SiteConfigDir 

func SiteConfigDir(name, author, version string) string

SiteConfigDir returns the full path to the user-shared configuration directory.

This function uses XDG_CONFIG_DIRS[0] as by the XDG spec on *nix like systems.

Examples of return values: 

Mac OS X: same as SiteDataDir
Unix: /etc/xdg/<AppName> or $XDG_CONFIG_DIRS[i]/<AppName> for each value in $XDG_CONFIG_DIRS
Win *: same as SiteDataDir
Vista: (Fail! "C:\ProgramData" is a hidden *system* directory on Vista.)

WARNING: Do not use this on Windows Vista, see the note above.

func SiteConfigDirs 

func SiteConfigDirs(name, author, version string) (paths []string)

func SiteDataDir 

func SiteDataDir(name, author, version string) string

SiteDataDir returns the full path to the user-shared data directory.

This function uses XDG_DATA_DIRS[0] as by the XDG spec on *nix like systems.

Examples of return values: 

Mac OS X: /Library/Application Support/<AppName>
Unix: /usr/local/share/<AppName> or /usr/share/<AppName>
Win XP: C:\Documents and Settings\All Users\Application Data\<AppAuthor>\<AppName>
Vista: (Fail! "C:\ProgramData" is a hidden *system* directory on Vista.)
Win 7: C:\ProgramData\<AppAuthor>\<AppName> # Hidden, but writeable on Win 7.

WARNING: Do not use this on Windows Vista, See the note above.

func SiteDataDirs 

func SiteDataDirs(name, author, version string) (paths []string)

Site path functions

func SiteLogDir 

func SiteLogDir(name, author, version string, opinion bool) string

SiteLogDir returns the full path to the user-shared log directory.

The opinion argument will append either 'Logs' (Windows and macOS) or 'log' (Unix) to the base directory when set to true on platforms that follow that convention.

Examples of return values: 

Mac OS X: /Library/Logs/<AppName>
Unix: /var/log/<AppName>
Windows: C:\ProgramData\<AppAuthor>\<AppName>\Logs

func SiteRuntimeDir 

func SiteRuntimeDir(name, author, version string) string

SiteRuntimeDir returns the full path to the shared runtime directory.

Examples of return values: 

Mac OS X: same as UserRuntimeDir
Unix (Linux): /run/<AppName>
Unix (BSD): /var/run/<AppName>
Windows: same as UserRuntimeDir

func SiteStateDir 

func SiteStateDir(name, author, version string) string

SiteStateDir returns the full path to the user-shared state directory.

Examples of return values: 

Mac OS X: same as SiteDataDir
Unix: /var/lib/<AppName>
Windows: same as SiteDataDir

func UserApplicationsDir 

func UserApplicationsDir() string

UserApplicationsDir returns the path to the user's applications directory.

Examples of return values: 

Mac OS X: ~/Applications
Unix: ~/.local/share/applications
Windows: C:\Users\<username>\AppData\Roaming\Microsoft\Windows\Start Menu\Programs

func UserBinDir 

func UserBinDir() string

UserBinDir returns the path to the user's binary directory.

Examples of return values: 

Mac OS X: ~/.local/bin
Unix: ~/.local/bin
Windows: C:\Users\<username>\AppData\Local\Programs

func UserCacheDir 

func UserCacheDir(name, author, version string, opinion bool) string

UserCacheDir returns the full path to the user-specific cache directory.

The opinion argument will append 'Cache' to the base directory if set to true.

Examples of return values: 

Mac OS X: ~/Library/Caches/<AppName>
Unix: ~/.cache/<AppName> (XDG default)
Win XP: C:\Documents and Settings\<username>\Local Settings\Application Data\<AppAuthor>\<AppName>\Cache
Vista: C:\Users\<username>\AppData\Local\<AppAuthor>\<AppName>\Cache

func UserConfigDir 

func UserConfigDir(name, author, version string, roaming bool) string

UserConfigDir returns the full path to the user-specific configuration directory

This function uses XDG_CONFIG_HOME as by the XDG spec on *nix like systems.

Examples of return values: 

Mac OS X: same as UserDataDir
Unix: ~/.config/<AppName> # or in $XDG_CONFIG_HOME, if defined
Win *: same as UserDataDir

func UserDataDir 

func UserDataDir(name, author, version string, roaming bool) string

UserDataDir returns the full path to the user-specific data directory.

This function uses XDG_DATA_HOME as defined by the XDG spec on *nix like systems.

Examples of return values: 

Mac OS X: ~/Library/Application Support/<AppName>
Unix: ~/.local/share/<AppName> # or in $XDG_DATA_HOME, if defined
Win XP (not roaming): C:\Documents and Settings\<username>\Application Data\<AppAuthor>\<AppName>
Win XP (roaming): C:\Documents and Settings\<username>\Local Settings\Application Data\<AppAuthor>\<AppName>
Win 7 (not roaming): C:\Users\<username>\AppData\Local\<AppAuthor>\<AppName>
Win 7 (roaming): C:\Users\<username>\AppData\Roaming\<AppAuthor>\<AppName>

func UserDesktopDir 

func UserDesktopDir() string

UserDesktopDir returns the path to the user's desktop directory.

Examples of return values: 

Mac OS X: ~/Desktop
Unix: ~/Desktop (or from XDG user-dirs configuration)
Windows: C:\Users\<username>\Desktop

func UserDocumentsDir 

func UserDocumentsDir() string

UserDocumentsDir returns the path to the user's documents directory.

Examples of return values: 

Mac OS X: ~/Documents
Unix: ~/Documents (or from XDG user-dirs configuration)
Windows: C:\Users\<username>\Documents

func UserDownloadsDir 

func UserDownloadsDir() string

UserDownloadsDir returns the path to the user's downloads directory.

Examples of return values: 

Mac OS X: ~/Downloads
Unix: ~/Downloads (or from XDG user-dirs configuration)
Windows: C:\Users\<username>\Downloads

func UserLogDir 

func UserLogDir(name, author, version string, opinion bool) string

UserLogDir returns the full path to the user-specific log directory.

The opinion argument will append either 'Logs' (windows) or 'log' (unix) to the base directory when set to true.

Examples of return values: 

Mac OS X: ~/Library/Logs/<AppName>
Unix: ~/.cache/<AppName>/log # or under $XDG_CACHE_HOME if defined
Win XP: C:\Documents and Settings\<username>\Local Settings\Application Data\<AppAuthor>\<AppName>\Logs
Vista: C:\Users\<username>\AppData\Local\<AppAuthor>\<AppName>\Logs

func UserMusicDir 

func UserMusicDir() string

UserMusicDir returns the path to the user's music directory.

Examples of return values: 

Mac OS X: ~/Music
Unix: ~/Music (or from XDG user-dirs configuration)
Windows: C:\Users\<username>\Music

func UserPicturesDir 

func UserPicturesDir() string

UserPicturesDir returns the path to the user's pictures directory.

Examples of return values: 

Mac OS X: ~/Pictures
Unix: ~/Pictures (or from XDG user-dirs configuration)
Windows: C:\Users\<username>\Pictures

func UserRuntimeDir 

func UserRuntimeDir(name, author, version string) string

UserRuntimeDir returns the full path to the user-specific runtime directory.

Examples of return values: 

Mac OS X: ~/Library/Caches/TemporaryItems/<AppName>
Unix (Linux): /run/user/<uid>/<AppName> # or under $XDG_RUNTIME_DIR if defined
Unix (BSD): /var/run/user/<uid>/<AppName> or /tmp/run/user/<uid>/<AppName>
Windows: C:\Users\<username>\AppData\Local\Temp\<AppAuthor>\<AppName>

func UserStateDir 

func UserStateDir(name, author, version string, roaming bool) string

UserStateDir returns the full path to the user-specific state directory.

Examples of return values: 

Mac OS X: same as UserDataDir
Unix: ~/.local/state/<AppName> (or under $XDG_STATE_HOME if defined)
Windows: same as UserDataDir

func UserVideosDir 

func UserVideosDir() string

UserVideosDir returns the path to the user's videos directory.

Examples of return values: 

Mac OS X: ~/Movies
Unix: ~/Videos (or from XDG user-dirs configuration)
Windows: C:\Users\<username>\Videos

Types

type App 

type App struct {
	Name    string
	Author  string
	Version string
	Roaming bool
	Opinion bool
}

App is a helper type to create easy access across your program to the appdirs functions.

The *App type has 6 methods that map to the 6 functions exported by `appdirs`. All methods take no arguments, and supply the function it wraps with arguments pre-set in the struct on creation.

func New 

func New(name string) *App

New returns a new App helper that has various methods for receiving relevant directories for your application.

The following defaults are used for the fields not settable by New: Author: "", Version: "", Roaming: false, Opinion: true

If you want to set these, create your own App struct by the usual means or modify the returned value accordingly.

func (*App) SiteApplications 

func (app *App) SiteApplications() string

SiteApplications returns the shared applications directory

func (*App) SiteBin 

func (app *App) SiteBin() string

SiteBin returns the shared bin directory

func (*App) SiteCache 

func (app *App) SiteCache() string

SiteCache returns the full path to the shared cache directory

func (*App) SiteConfig 

func (app *App) SiteConfig() string

SiteConfig returns the full path to the user-shared configuration directory

func (*App) SiteData 

func (app *App) SiteData() string

SiteData returns the full path to the user-shared data directory

func (*App) SiteLog 

func (app *App) SiteLog() string

SiteLog returns the full path to the shared log directory

func (*App) SiteRuntime 

func (app *App) SiteRuntime() string

SiteRuntime returns the full path to the shared runtime directory

func (*App) SiteState 

func (app *App) SiteState() string

SiteState returns the full path to the shared state directory

func (*App) UserApplications 

func (app *App) UserApplications() string

UserApplications returns the user's applications directory

func (*App) UserBin 

func (app *App) UserBin() string

UserBin returns the user's bin directory

func (*App) UserCache 

func (app *App) UserCache() string

UserCache returns the full path to the user-specific cache directory

func (*App) UserConfig 

func (app *App) UserConfig() string

UserConfig returns the full path to the user-specific configuration directory

func (*App) UserData 

func (app *App) UserData() string

UserData returns the full path to the user-specific data directory

func (*App) UserDesktop 

func (app *App) UserDesktop() string

UserDesktop returns the user's desktop directory

func (*App) UserDocuments 

func (app *App) UserDocuments() string

UserDocuments returns the user's documents directory

func (*App) UserDownloads 

func (app *App) UserDownloads() string

UserDownloads returns the user's downloads directory

func (*App) UserLog 

func (app *App) UserLog() string

UserLog returns the full path to the user-specific log directory

func (*App) UserMusic 

func (app *App) UserMusic() string

UserMusic returns the user's music directory

func (*App) UserPictures 

func (app *App) UserPictures() string

UserPictures returns the user's pictures directory

func (*App) UserRuntime 

func (app *App) UserRuntime() string

UserRuntime returns the full path to the user-specific runtime directory

func (*App) UserState 

func (app *App) UserState() string

UserState returns the full path to the user-specific state directory

func (*App) UserVideos 

func (app *App) UserVideos() string

UserVideos returns the user's videos directory

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.