# Beets: Python Music Library Manager and MusicBrainz Tagger

> Beets is an MIT-licensed Python command-line music library manager that automatically corrects track and album metadata by querying MusicBrainz during import. It organizes files on disk according to configurable templates and extends through a plugin system that adds features ranging from album art fetching to audio transcoding.

**beetbox/beets** — music library manager and MusicBrainz tagger

- Repository: https://github.com/beetbox/beets
- Website: http://beets.io/
- Stars: 15,731 · Forks: 2,129
- Language: Python
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/beetbox-beets

## What Beets Does and Who Uses It

Beets is a music library management system described in the README as being for 'obsessive music geeks'. Its core function is importing music files, matching them against the MusicBrainz database, correcting metadata tags where they differ from the authoritative release information, and organizing the files in a directory structure controlled by a user-defined template.

The project is by Adrian Sampson and a large community of contributors. It targets users with large music collections, particularly those whose existing files have inconsistent, incomplete, or incorrect metadata from years of ripping, downloading, or streaming. Once the collection is imported, beets provides a suite of CLI tools for querying, editing, and processing the library.

The Python version constraint in pyproject.toml is Python 3.10 through 3.14. The current version is 2.14.1, released on 2026-09-17.

## The Import Process and Automatic Tag Correction

The README provides an example of beets correcting a set of Ladytron tracks. During import, beets queries MusicBrainz for a match based on the existing file metadata and audio fingerprint, then shows the differences:

```
$ beet import ~/music/ladytron
Tagging:
    Ladytron - Witching Hour
(Similarity: 98.4%)
 * Last One Standing      -> The Last One Standing
 * Beauty                 -> Beauty*2
 * White Light Generation -> Whitelightgenerator
 * All the Way            -> All the Way...
```

Each difference is shown before any changes are made, and the user can accept, reject, or manually override the match. The similarity score (98.4% in this example) reflects how closely the found MusicBrainz release matches the imported tracks. Low similarity scores prompt for manual confirmation.

Beets also supports guessing metadata from filenames and from acoustic fingerprints (via the chroma plugin), which means it can tag files with completely incorrect or missing tags if the audio content matches a known release.

## Installing Beets

Beets installs from PyPI with pip:

```bash
pip install beets
```

The README also mentions that beets has been packaged in the software repositories of several Linux distributions, with a current package list at repology.org/project/beets/versions. Running from the latest development source is documented in the FAQ at beets.readthedocs.io.

The core dependencies listed in pyproject.toml include mediafile 0.17.0+ (for reading and writing audio file tags), jellyfish (for fuzzy string matching during tagging), confuse 2.2.0+ (for configuration management), numpy (for audio analysis features), pyyaml (for the configuration file), and requests 2.32.5+ with requests-ratelimiter for external API calls.

After installation, beets is configured through a YAML file. The getting started guide at beets.readthedocs.org/page/guides/main.html walks through initial configuration.

## Plugin System: Expanding What Beets Can Do

Beets ships with a core set of features and extends through plugins, many of which are included in the beetsplug/ directory in the repository. The plugin system is described in the README as making beets a panacea, meaning the base tool handles import and tagging while plugins add specialized functions.

Plugins documented in the README cover a wide range of post-import tasks. The fetchart plugin downloads album artwork. The lyrics plugin fetches lyrics. The lastgenre plugin assigns genres. The chroma plugin adds acoustic fingerprint matching. The replaygain plugin calculates replay gain levels. The convert plugin transcodes audio to different formats. The duplicates plugin checks the library for duplicate tracks and albums. The missing plugin identifies albums that are missing tracks.

Additional metadata sources available through plugins include Discogs and Beatport, supplementing the built-in MusicBrainz queries. The web plugin provides a browser-based interface that plays music using the HTML5 Audio element. The bpd plugin exposes an MPD-compatible server for use with MPD client software.

Writing a custom plugin requires Python knowledge. The README notes that writing your own plugin is 'shockingly simple if you know a little Python', and the documentation at beets.readthedocs.org/page/dev/plugins/index.html covers the plugin API.

## Querying and Modifying the Library

After import, the beet command provides tools for querying and modifying the library. The beet list command queries the library using beets's own query language, which supports matching on any tag field, substring search, and boolean operators. The beet modify command applies tag changes to matching tracks.

The library is stored in a local database (SQLite-based, via the mediafile library). This means queries are fast and do not require re-reading audio files. The beet update command re-reads files from disk to catch changes made by other tools.

The README mentions a command-line audio metadata analysis function without naming it specifically. The beet stats command provides library statistics. The beet move command reorganizes files to match the current template if the configuration has changed since import.

## Where Beets Falls Short

Beets has no graphical interface. Every operation is run from the command line or configured in YAML. This is a deliberate design choice, not an oversight, but it means the tool is inaccessible to users who are not comfortable with a terminal.

The import process is potentially slow for very large collections because each track requires a MusicBrainz API query (subject to rate limiting) unless acoustic fingerprints are precomputed in batch. The requests-ratelimiter dependency is present specifically to respect MusicBrainz's API rate limits, which means a large import can take hours.

Some plugins require additional system dependencies. The chroma plugin for acoustic fingerprinting requires the Chromaprint library. The convert plugin requires FFmpeg for transcoding. These are not installed automatically by pip and must be installed separately. Plugin requirements are documented individually in the beets documentation but not in the core README.

## Beets versus MusicBrainz Picard

MusicBrainz Picard is the official desktop tagger for MusicBrainz. It provides a graphical interface for the same core function: matching music files against MusicBrainz and correcting tags. The key practical difference is that Picard is a point-and-click application while beets is a CLI tool with a programmable configuration and plugin system.

For organizing large collections according to a consistent template and running batch operations (transcoding, artwork fetching, duplicate detection) as part of a single import workflow, beets is more practical than Picard because each step can be automated. Picard requires manual interaction for each album.

Picard works for users who prefer a visual review of tag changes and occasional one-off correction of specific albums. Beets is better suited when the goal is to process an entire collection consistently according to rules defined in the configuration file, with plugins adding each post-import step automatically during or after import.

## Conclusion

Beets suits users with large music collections who want accurate, verifiable metadata and are comfortable with a command-line tool and YAML configuration. It is the wrong tool for users who prefer a graphical interface or need to process only a small collection occasionally, since the setup overhead (configuration file, plugin selection, and import process) is not justified for casual use. Before running a full import, test the configuration on a small subset to verify the directory template and tag correction settings match the desired output.

## FAQ

### How do you use beets for music management?

Run beet import on a directory of music files. Beets queries MusicBrainz for each album, shows proposed tag corrections, and organizes files according to a directory template defined in the YAML configuration file. Plugins add features such as album art fetching, lyrics, and audio transcoding.

### How do you install beets?

Install beets from PyPI with pip install beets. Beets requires Python 3.10 or later. Some plugins require additional system dependencies such as Chromaprint for acoustic fingerprinting or FFmpeg for audio transcoding, which must be installed separately.

### What metadata sources does beets use?

Beets queries MusicBrainz by default during import. Additional sources are available through plugins: the Discogs plugin queries the Discogs database, the Beatport plugin queries Beatport, and the chroma plugin uses acoustic fingerprints via Chromaprint to match files that have incorrect or missing tags.

## Sources

- [beetbox/beets on GitHub](https://github.com/beetbox/beets)
- [License: MIT](https://github.com/beetbox/beets/blob/master/LICENSE)
- [Project website](http://beets.io/)
- [README](https://github.com/beetbox/beets/blob/master/README.md)
- [Releases](https://github.com/beetbox/beets/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/beetbox-beets