Why Your Music Library Is Probably a Mess
A music collection built over years – pulled from CDs, downloaded from the web, ripped from vinyl transfers, grabbed off various platforms – tends to become an organizational nightmare. Track numbers are wrong, album art is missing, artist names are inconsistently formatted, and genre tags are a chaotic mix of whatever the original source decided to use. Playing music in any app becomes a game of hunting down files you know you have but can’t locate. Beets, a free and open-source command-line tool, exists specifically to fix this problem.
Beets works by scanning your music files, querying the MusicBrainz database to match each track against verified metadata, and then rewriting your file tags and renaming your folder structure according to rules you define. It handles MP3, FLAC, AAC, OGG, and most other common formats. The initial setup takes about 20 minutes, and after that, importing new music is a single command. This guide walks through installation, configuration, and practical usage on Linux, macOS, and Windows.
Installing Beets on Your System
Beets requires Python 3.6 or higher. On most Linux distributions and macOS, Python is already installed. Open a terminal and run python3 –version to confirm. On Windows, download Python from python.org and make sure to check “Add Python to PATH” during installation before proceeding. With Python confirmed, install Beets using pip by running pip3 install beets. If you want the full set of optional plugins – including album art fetching, ReplayGain normalization, and last.fm scrobbling – install with pip3 install beets requests pylast Pillow instead.
After installation, verify everything worked by running beet version in your terminal. You should see the current Beets version printed along with a list of available plugins. On Linux, if the beet command is not found after pip install, your local bin directory may not be in your PATH. Add export PATH=”$HOME/.local/bin:$PATH” to your ~/.bashrc or ~/.zshrc file, then reload your shell with source ~/.bashrc. Windows users running into PATH issues after installation should restart the terminal entirely before troubleshooting further.
Configuring Beets for Auto-Tagging
Beets stores its configuration in a YAML file located at ~/.config/beets/config.yaml on Linux and macOS, or at %APPDATA%\beets\config.yaml on Windows. This file does not exist by default – you create it yourself. The configuration you write here controls where your music library lives, how files get renamed, which plugins are active, and how aggressively Beets matches tracks against the MusicBrainz database.
A functional starting configuration looks like this. Set directory to the folder where you want your organized music to live – for example, /home/yourname/Music. Set library to the path for Beets’s internal SQLite database, typically /home/yourname/.config/beets/library.db. Under the import section, set copy: yes if you want Beets to copy files to the new directory while leaving originals in place, or move: yes if you want it to relocate files outright. During a first run, copy: yes is safer – it lets you verify the results before committing.
The path template controls exactly how Beets names and folders your files after tagging. Under a paths section in config.yaml, set default to something like $albumartist/$album%aunique{}/$track – $title. This creates a folder per artist, a subfolder per album, and names each file with track number and title. The %aunique{} function appends a year or disambiguation tag automatically when an artist has two albums with the same name, which is more common than you’d expect. You can also define separate path rules for singles, compilations, and soundtrack albums using Beets’s query syntax.
Enabling plugins in the config file is straightforward. Add a plugins: line followed by a list of plugin names. The most useful ones for a standard library setup are fetchart (downloads album artwork and embeds it in the file), embedart (controls how artwork is embedded), lyrics (fetches and stores lyrics as file tags), and duplicates (identifies duplicate tracks in your library). Each plugin can take its own configuration block below the main settings. For fetchart, setting auto: yes tells Beets to fetch art automatically during import without asking.
Running Your First Import
With configuration in place, point Beets at your existing music folder by running beet import /path/to/your/music. Beets scans every audio file it finds, groups tracks into albums or singles, and then queries MusicBrainz for the best match. For each album, it presents a match with a similarity score – anything above 95% is usually correct. You can press A to accept the match, M to manually search with a different query, E to edit tags by hand, or S to skip the album entirely and leave it untagged.
For libraries with hundreds or thousands of albums, interactive import is impractical. Run beet import -A /path/to/your/music to use automatic mode, where Beets accepts any match above the confidence threshold and skips anything it cannot match confidently. After the import finishes, run beet import -A –timid /path/to/your/music on a second pass to review only the items that were skipped. This two-pass approach handles large libraries efficiently while still giving you manual control over the hard cases.
Querying and Managing Your Library
Once your music is imported, Beets provides a query language for searching and managing the database. Run beet list artist:Radiohead to list every Radiohead track in your library. Run beet list year:2010..2020 genre:jazz to pull every jazz album released in that decade. Queries can be combined with any tag Beets stores, including BPM, label, country of release, and MusicBrainz IDs. This is where the tagging investment pays off – you can build playlists and smart queries that would be impossible with messy, inconsistent tags.
To update tags on files already in your library, use beet modify. For example, beet modify genre=”Electronic” artist:Aphex Twin overwrites the genre tag on every Aphex Twin track at once. The beet update command checks your library database against the actual files on disk and syncs any changes. If you have edited files in an external tagger and want Beets to reflect those changes, run beet update after. For removing duplicate files identified by the duplicates plugin, run beet duplicates -d – but review the list with beet duplicates first before adding the delete flag.
The beet stats command gives you a quick breakdown of your library – total tracks, total playtime, number of artists and albums, and how much disk space the collection occupies. It won’t reorganize anything, but it’s a useful sanity check after a large import to confirm the numbers look right before you delete your original unorganized folder.
One detail worth getting right before your first import: make sure your directory and library paths in config.yaml point to locations with enough storage. Beets does not warn you if it runs out of disk space mid-import – it just stops, leaving your library in a partially migrated state that takes real effort to untangle.
