{"id":27611,"library":"beets","title":"beets","description":"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.","status":"active","version":"2.11.0","language":"python","source_language":"en","source_url":"https://github.com/beetbox/beets","tags":["music","tagger","library","metadata","id3","flac","mp3"],"install":[{"cmd":"pip install beets","lang":"bash","label":"Basic install"},{"cmd":"pip install beets[discogs,lyrics,chroma]","lang":"bash","label":"Install with common plugins"}],"dependencies":[{"reason":"Required for audio file metadata handling.","package":"mutagen","optional":false},{"reason":"Required for MusicBrainz metadata lookup.","package":"musicbrainzngs","optional":false},{"reason":"Used for metadata normalization.","package":"unidecode","optional":false},{"reason":"Used for string similarity in matching.","package":"jellyfish","optional":false},{"reason":"Required for configuration file parsing.","package":"pyyaml","optional":false},{"reason":"Required since v2.6.1 for version comparisons.","package":"packaging","optional":false}],"imports":[{"note":"Library is a top-level attribute in v2.x, not in a submodule.","wrong":"from beets.library import Library","symbol":"Library","correct":"from beets import Library"},{"note":"Item is defined in beets.library, not top-level.","wrong":"from beets import Item","symbol":"Item","correct":"from beets.library import Item"},{"note":"ui is a module, not a class.","wrong":"from beets.ui import ui","symbol":"ui","correct":"from beets import ui"},{"note":"config is a singleton instance in beets module.","wrong":"from beets.config import config","symbol":"config","correct":"from beets import config"}],"quickstart":{"code":"from beets import Library\nfrom beets.library import Item\n\nlib = Library(':memory:')  # in-memory database for testing\n\n# Add an item\nitem = Item(lib, path='/path/to/song.mp3')\nitem.title = 'Test Song'\nitem.artist = 'Test Artist'\nlib.add(item)\nlib.store()\n\n# Query items\nitems = lib.items('artist:test')\nfor i in items:\n    print(i.title, i.artist)\n","lang":"python","description":"Initialize an in-memory beets library, add an item, and query it."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.10.0"},{"fix":"Update any scripts that parse 'splupdate' output to handle the new format. Use --format to customize track line format if needed.","message":"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.","severity":"breaking","affected_versions":">=2.11.0"},{"fix":"Define only one plugin class per file, or use the 'beet' entry point to specify the class.","message":"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.","severity":"deprecated","affected_versions":">=2.5.1"},{"fix":"Run 'beet config -p' to show the path where beets expects config. Use 'beet config -e' to edit the file.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Use 'beet import -t /path' for interactive mode, or configure 'import: timid: yes' in config.","message":"When using the 'import' command with '-t' (timid) mode, beets performs a slow, interactive deduplication. Not setting '-t' can lead to unexpected duplicates.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Install beets: pip install beets","cause":"beets is not installed or not in the current Python environment.","error":"ModuleNotFoundError: No module named 'beets'"},{"fix":"Use: from beets import Library","cause":"Trying to import Library from the wrong submodule.","error":"ImportError: cannot import name 'Library' from 'beets'"},{"fix":"Use: from beets.library import Item","cause":"Trying to import Item from the beets top-level, but it is in beets.library.","error":"ImportError: cannot import name 'Item' from 'beets'"},{"fix":"Ensure the item is added to a library (lib.add(item)) and then lib.store() before accessing item.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.","error":"KeyError: 'path'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}