dirs-rs

dirs is a tiny, low-level Rust library that provides the platform-specific, user-accessible locations for storing and retrieving configuration, cache, and other application data. It resolves the correct paths by following each operating system’s native conventions: the XDG base and user directory specifications on Linux and Redox, the Known Folder API on Windows, and the Standard Directories guidelines on macOS.

With a minimal API of 18 standalone functions such as home_dir(), config_dir(), and cache_dir(), the crate returns an Option<PathBuf> for each well-known directory without ever creating folders or checking for their existence. It is intentionally focused on user-writable directories, making it a dependable foundation for any cross-platform tool that needs to know where files belong.

What You Get

• A minimal API of 18 standalone functions covering home, config, cache, data, state, runtime, and executable directories.
• User-directory helpers for common folders such as audio, desktop, documents, downloads, pictures, and videos.
• Correct path resolution across Linux, Redox, macOS, iOS, Windows (Vista and later), and WebAssembly.
• A dependency-light footprint that builds on the companion dirs-sys crate for the low-level system calls.

Common Use Cases

• Locating a writable config directory so a CLI tool can persist user settings across sessions.
• Choosing a cache directory to store downloaded or computed artifacts without polluting the home folder.
• Resolving a data directory for application state that should survive restarts.
• Building cross-platform desktop or command-line tools that must respect native OS folder conventions.

Under The Hood

Architecture

The crate is organized as a thin, platform-dispatching facade in src/lib.rs, which exposes 18 documented public functions and delegates each call to a platform module selected at compile time via cfg attributes: win.rs for Windows, mac.rs for macOS and iOS, wasm.rs for wasm32, and lin.rs as the fallback for Linux, Redox, and other Unix-like systems (aliased as sys). Each backend implements the same function set independently — for example lin.rs resolves config_dir() by reading $XDG_CONFIG_HOME and falling back to $HOME/.config, while mac.rs returns ~/Library/Application Support — so the public API stays identical while behavior follows native OS conventions. Low-level system access (reading the home directory via getpwuid_r, calling SHGetKnownFolderPath, parsing XDG user-dir files) is deferred to the companion dirs-sys crate.

Tech Stack

Written in pure Rust (roughly 23 KB of source across five files) with a single runtime dependency, dirs-sys 0.5.0, which in turn wraps windows-sys for the Known Folder API on Windows. The crate has no build script, uses the standard cargo toolchain, and targets a very old minimum Rust version (1.13 on most platforms), reflecting its stable, low-churn design. It is dual-licensed MIT OR Apache-2.0.

Code Quality

The code is exceptionally compact and readable: platform modules are written as one-line function bodies chaining env::var_os, and_then, and or_else over Option<PathBuf>, which keeps the fallback logic explicit and side-effect free. #![deny(missing_docs)] enforces that every public function carries documentation, and each is accompanied by a per-platform value table in its doc comment. Testing is light — a couple of #[cfg(test)] smoke tests exist in lib.rs and lin.rs (e.g. checking for a user-dirs.dirs file) rather than a comprehensive suite — which is a reasonable trade-off given the logic is a thin, declarative mapping to OS conventions.

API Design

The public API is about as ergonomic as it gets: flat, free-standing functions with self-describing names (home_dir, cache_dir, config_dir, runtime_dir) that each return Option<PathBuf>, requiring zero setup, no structs to construct, and no error handling beyond a None check. Documentation is a standout — every function includes a table mapping the returned value across Linux, macOS, and Windows with concrete examples — and the README clearly steers users toward the sister directories crate when they need project-scoped paths, setting expectations rather than over-promising.