beets

library2.11.0pypypiunverified

beets is a music tagger and library organizer. Current version is 2.11.0, requiring Python >=3.10 and <3.15. Releases follow an irregular cadence with multiple minor versions per year.

database serialization

pip install beets

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · BEETS

beets

databasepythonv2.11.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Library

✓ from beets import Library

✗ from beets import Library

Initialize an in-memory beets library, add an item, and query it.

from beets import Library from beets.library import Item lib = Library(':memory:') # in-memory database for testing # Add an item item = Item(lib, path='/path/to/song.mp3') item.title = 'Test Song' item.artist = 'Test Artist' lib.add(item) lib.store() # Query items items = lib.items('artist:test') for i in items: print(i.title, i.artist)

beet --version

Debug

Known issues

breakingSince v2.10.0, item and album-art paths are stored relative to library root in the database. Existing paths are migrated automatically on first run, but manual database edits or external scripts may break if they assume absolute paths.

fix

Use lib.directory to get the library root and join relative paths, or continue to use absolute paths in queries (they still match). Avoid direct DB manipulation.

affects: >=2.10.0

breakingSince v2.11.0, the splupdate command output has changed: per-playlist summary includes track count, per-track details only shown with -v, and --pretend reports 'N playlists would be updated' instead of 'N playlists updated'. Scripts parsing splupdate output will break.

fix

Update any scripts that parse 'splupdate' output to handle the new format. Use --format to customize track line format if needed.

affects: >=2.11.0

deprecatedbeets.plugins.BeetsPlugin: loading the last plugin class defined in the plugin namespace is deprecated. Multiple classes in one file may cause unexpected behavior since v2.5.1.

fix

Define only one plugin class per file, or use the 'beet' entry point to specify the class.

affects: >=2.5.1

gotchaConfiguration file path: beets looks for config.yaml in multiple locations (e.g., XDG config home). Ensure your config is in the expected location, otherwise beets may use defaults silently.

fix

Run 'beet config -p' to show the path where beets expects config. Use 'beet config -e' to edit the file.

affects: all

gotchaWhen using the 'import' command with '-t' (timid) mode, beets performs a slow, interactive deduplication. Not setting '-t' can lead to unexpected duplicates.

fix

Use 'beet import -t /path' for interactive mode, or configure 'import: timid: yes' in config.

affects: all

Upgrade

Version history

2.11.0latest on PyPI · released May 6, 2026

Audit

Dependencies

mutagenrequiredRequired for audio file metadata handling.

musicbrainzngsrequiredRequired for MusicBrainz metadata lookup.

unidecoderequiredUsed for metadata normalization.

jellyfishrequiredUsed for string similarity in matching.

pyyamlrequiredRequired for configuration file parsing.

packagingrequiredRequired since v2.6.1 for version comparisons.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/beetbox/beets ↗

packagehttps://pypi.org/project/beets/ ↗

homepagehttps://beets.io/ ↗

docshttps://beets.readthedocs.io/en/stable/ ↗

changeloghttps://github.com/beetbox/beets/blob/master/docs/changelog.rst ↗