Where Does beets Store Config and Library?
beets keeps its YAML config and SQLite library database in platform config folders. Config paths, BEETSDIR, and commands.
Last updated
beets keeps two files that matter: config.yaml with every setting, and library.db, the SQLite index of your music. Both live in the platform config folder, Unix ~/.config/beets, Windows Roaming\beets, macOS either of those or application support. The music itself lives wherever the directory line says, often far away.
The config may not exist until you create it, which confuses first-timers hunting for a file that was never written. beet config -e creates and opens it; beet config -p prints its path. BEETSDIR overrides the whole location for portable or synced setups. YAML means spaces, never tabs, or the file silently misbehaves.
Where beets stores this, by platform
~/.config/beets/config.yaml
config.yaml holds all settings; library.db sits beside it by default. May not exist until created via beet config -e. BEETSDIR overrides the location entirely. YAML syntax: spaces only, never tabs. Music lives at the directory path inside the config, not here.
%APPDATA%\beets\config.yaml
Same filenames as Linux under Roaming. Use beet config -p to confirm the effective file when BEETSDIR or odd APPDATA setups confuse matters. Music defaults to ~/Music unless the directory line says otherwise.
~/.config/beets/config.yaml
Prefers ~/.config/beets like other Unixes, with ~/Library/Application Support/beets as the alternate. beets searches the application-support path before the Unix one. Same config.yaml and library.db pair either way.
Frequently asked questions
how do i move beets to a new computer
Copy config.yaml and library.db to the new machine's beets config path, keeping relative music paths valid. If music moves too, update the directory and library lines to the new spots. Plugins reinstall via pip; their settings travel inside config.yaml already.
which config file is beets actually using
Run beet config -p. It prints the exact file beets will use on your system, cutting through BEETSDIR overrides and platform differences. beet config -e opens that file in your editor, creating it if missing. Diagnose path confusion with -p before editing anything.
how do i relocate the beets config folder
Set the BEETSDIR environment variable to a folder holding config.yaml. Beets uses it instead of the platform default, and the library database resolves beside it too. Point BEETSDIR at a synced folder and your whole setup roams across machines.
what is the old beetsconfig file
That is the version 1.0 era location. Modern beets uses config.yaml in the platform config folder, not INI-style .beetsconfig. Migrate the library and directory lines by hand; the formats are not compatible. Current docs only describe the YAML layout.
Notice an outdated path? Let us know.