beets

2.11.0 verified Sat May 09 auth: no python

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.

pip install beets

Common errors

error ModuleNotFoundError: No module named 'beets' ↓

cause beets is not installed or not in the current Python environment.

fix

Install beets: pip install beets

error ImportError: cannot import name 'Library' from 'beets' ↓

cause Trying to import Library from the wrong submodule.

fix

Use: from beets import Library

error ImportError: cannot import name 'Item' from 'beets' ↓

cause Trying to import Item from the beets top-level, but it is in beets.library.

fix

Use: from beets.library import Item

error KeyError: 'path' ↓

cause Trying to access item.path as a simple attribute, but path is stored as a property that may raise error if item is not in database.

fix

Ensure the item is added to a library (lib.add(item)) and then lib.store() before accessing item.path.

Warnings

breaking Since 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.

breaking Since 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.

deprecated beets.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.

gotcha Configuration 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.

gotcha When 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.

Install

pip install beets[discogs,lyrics,chroma]

Imports

Library
wrong
```
from beets.library import Library
```
correct
```
from beets import Library
```
Library is a top-level attribute in v2.x, not in a submodule.
Item
wrong
```
from beets import Item
```
correct
```
from beets.library import Item
```
Item is defined in beets.library, not top-level.

wrong

from beets.ui import ui

correct

from beets import ui

ui is a module, not a class.

config
wrong
```
from beets.config import config
```
correct
```
from beets import config
```
config is a singleton instance in beets module.

Quickstart

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)