selfhost.directory

The index of self-hostable projects — ranked, categorized and served with live updates.
Own your data and stop giving it to big tech.

Beets logo

Self-host Beets

v2.14.1

Music library manager that auto-fixes tags from MusicBrainz

ReleaseOpen SourceMIT
pip install beets
Updatedlast month
LanguagePython
Setup difficultyModerate
Stars
15 941
Ports
8337 (Web plugin's browser UI and REST+JSON API server (bound to 127.0.0.1 by default)), 6600 (BPD plugin, a music player daemon that speaks the MPD protocol)
The beets web plugin's browser interface for searching and playing the library

What is Beets?

beets is a Python media library manager for people who want their music metadata fixed once and kept clean. Its interactive autotagger catalogues a collection and corrects tags by matching against MusicBrainz and, through plugins, sources such as Discogs and Beatport; it can also fetch artwork, lyrics, genres, tempos and ReplayGain levels, compute acoustic fingerprints, transcode audio, flag duplicates or albums missing tracks, and reorganise files using configurable path formats. Day-to-day work happens in the beet command line (list, import, move, stats), and behaviour is extended either through bundled plugins or plugins you write yourself in Python. Two optional servers come from the same library database: a web interface backed by a REST+JSON API that plays tracks with HTML5 audio, and BPD, a daemon that speaks the MPD protocol so ordinary MPD clients can drive your collection. Install it with pip, uv tool, pipx or your distribution's package (Python 3.10 or later); configuration lives in a YAML file such as ~/.config/beets/config.yaml, and the web or BPD features need their own extras (pip install "beets[web]", pip install "beets[bpd]").

Should you self-host Beets?

Beets scores 77/100 on selfhost.directory (how scoring works) and ranks #1 of 32 in Music. It has 15 941 GitHub stars, +162 in the last 30 days.

It shipped 14 stable releases in the past year. The latest, v2.14.1, came out on 17 September 2026. New versions land roughly every 2 weeks.

Setup is moderate: expect some configuration beyond a single command. It is MIT-licensed and written mostly in Python.

Its closest alternative on selfhost.directory is MusicBot (68/100, 5 806 stars). Beets scores higher overall. See Beets vs MusicBot side by side.

Features

  • Audio Transcoding
  • Automatic music tagging (autotagger)
  • Command Line Interface
  • Configurable file organization and renaming
  • Duplicate and missing-track detection
  • Embed and extract album art
  • Metadata enrichment (artwork, lyrics, genres, ReplayGain, fingerprints)
  • MPD-protocol music player daemon
  • Plugin System
  • REST + JSON API
  • Tag cleanup
  • Web interface for browsing and playingRequires the web extra: pip install "beets[web]"

Beets README

How to install Beets

Install Beets with pip

pip install beets

or for a user-only install:

pip install --user beets

Recommended by the docs because it isolates beets and its dependencies from the system Python.

How to configure Beets

  • libraryPath to the beets library file; by default a file called library.db alongside your configuration file.
  • directoryThe directory to which files will be copied/moved when adding them to the library.
  • pluginsA space-separated list of plugin module names to load.
  • art_filenameName to use for album art files (see the example config: art_filename: albumart).
  • id3v23Write ID3v2.3 tags instead of the default ID3v2.4 for software that cannot read 2.4.

    values: yes, no

Beets releases & version history

@ Every self-hosted release, weekly

One Monday email with the week's stable releases across the directory.

FAQ

Why does beets not change my ID3 tags?

beets writes ID3v2.4 tags by default, which some software (Windows Explorer, Windows Media Player, id3lib) cannot read; enable the id3v23 option to write 2.3 tags instead.

Why does beets ignore control-C during an import?

The importer's UI thread is blocked waiting for input, so press Return or type "b" to abort at a prompt; beets also takes a moment to clean up after ^C.

Why does beets appear to be missing some plugins?

The plugin is probably newer than the version you installed; check the changelog for the version that introduced it (beet version shows what you have).

Why does beets complain that it can't find a match?

Check that at least one autotagger plugin is enabled, that the release exists in MusicBrainz, and that the files carry enough metadata; otherwise use the manual search/enter-ID options, acoustic fingerprinting or filename-based guessing.

How do I point beets at a new music directory?

Change the directory setting to the new place and run beet move; if the files already moved outside beets, delete the database and rebuild it from the new paths.

How do I avoid using special characters in my filenames?

Use the %asciify{} template function inside your path formats.

How do I report a bug in beets?

Use the GitHub issue tracker, including any traceback plus verbose output from the -v option, and narrow the problem down to a plugin, file or config entry if you can.

How do I run the latest source version of beets?

Uninstall the packaged version first, then install the source: a git+https pip install, the latest master tarball, or an editable clone of the repository.

How do I upgrade to the latest version of beets?

Upgrade through pip: the -U flag tells pip to bring beets up to the latest release, and you can pin a specific version with ==.

How do I import a multi-disc album?

beets tags all parts of a multi-disc release together, guessing from directory names that contain words such as "disc", "CD" or "vinyl"; if matching fails, use the --flat flag or put the files in a single directory.

How do I create "Disc N" directories for multi-disc albums?

Use the inline plugin together with the %if{} template function so the path format only inserts a "Disc N" folder when an album has more than one disc.

How do I find all the albums I imported "as-is"?

Enable the import log, which records whenever you skip an album or accept one as-is, or list albums that have no MusicBrainz ID with a query such as beet ls -a mb_albumid::^$.

How do I rename my files according to a new path format configuration?

Run the move command; pass a query to rename only part of the collection, or leave the query off to rename everything.

More in Music

Rate this project

Click to rate — no account needed.

0 comments

Posting as guest
Loading comments…