FAQ¶

Here are some answers to frequently-asked questions from IRC and elsewhere. Got a question that isn’t answered here? Try the discussion board, or filing an issue in the bug tracker.

How do I…¶

…rename my files according to a new path format configuration?¶

Just run the move command. Use a query to rename a subset of your music or leave the query off to rename everything.

…find all the albums I imported “as-is”?¶

Enable the import log to automatically record whenever you skip an album or accept one “as-is”.

Alternatively, you can find all the albums in your library that are missing MBIDs using a command like this:

beet ls -a mb_albumid::^$

Assuming your files didn’t have MBIDs already, then this will roughly correspond to those albums that didn’t get autotagged.

…create “Disc N” directories for multi-disc albums?¶

Use the Inline Plugin along with the %if{} function to accomplish this:

plugins: inline
paths:
    default: $albumartist/$album%aunique{}/%if{$multidisc,Disc $disc/}$track $title
item_fields:
    multidisc: 1 if disctotal > 1 else 0

…import a multi-disc album?¶

As of 1.0b11, beets tags multi-disc albums as a single unit. To get a good match, it needs to treat all of the album’s parts together as a single release.

To help with this, the importer uses a simple heuristic to guess when a directory represents a multi-disc album that’s been divided into multiple subdirectories. When it finds a situation like this, it collapses all of the items in the subdirectories into a single release for tagging.

The heuristic works by looking at the names of directories. If multiple subdirectories of a common parent directory follow the pattern “(title) disc (number) (…)” and the prefix (everything up to the number) is the same, the directories are collapsed together. One of the key words “disc” or “CD” must be present to make this work.

If you have trouble tagging a multi-disc album, consider the --flat flag (which treats a whole tree as a single album) or just putting all the tracks into a single directory to force them to be tagged together.

…enter a MusicBrainz ID?¶

An MBID looks like one of these:

https://musicbrainz.org/release/ded77dcf-7279-457e-955d-625bd3801b87
d569deba-8c6b-4d08-8c43-d0e5a1b8c7f3

Beets can recognize either the hex-with-dashes UUID-style string or the full URL that contains it (as of 1.0b11).

You can get these IDs by searching on the MusicBrainz web site and going to a release page (when tagging full albums) or a recording page (when tagging singletons). Then, copy the URL of the page and paste it into beets.

Note that MusicBrainz has both “releases” and “release groups,” which link together different versions of the same album. Use release IDs here.

…upgrade to the latest version of beets?¶

Run a command like this:

pip install -U beets

The -U flag tells pip to upgrade beets to the latest version. If you want a specific version, you can specify with using == like so:

pip install beets==1.0rc2

…run the latest source version of beets?¶

Beets sees regular releases (about every six weeks or so), but sometimes it’s helpful to run on the “bleeding edge”. To run the latest source:

Uninstall beets. If you installed using pip, you can just run pip uninstall beets.
Install from source. Choose one of these methods:
- Use pip to install the latest snapshot tarball. Type: pip install https://github.com/beetbox/beets/tarball/master
- Grab the source using git. First, clone the repository: git clone https://github.com/beetbox/beets.git. Then, cd beets and python setup.py install.
- Use pip to install an “editable” version of beets based on an automatic source checkout. For example, run pip install -e git+https://github.com/beetbox/beets#egg=beets to clone beets and install it, allowing you to modify the source in-place to try out changes.
- Combine the previous two approaches, cloning the source yourself, and then installing in editable mode: git clone https://github.com/beetbox/beets.git then pip install -e beets. This approach lets you decide where the source is stored, with any changes immediately reflected in your environment.

More details about the beets source are available on the developer documentation pages.

…report a bug in beets?¶

We use the issue tracker on GitHub. Enter a new issue there to report a bug. Please follow these guidelines when reporting an issue:

Most importantly: if beets is crashing, please include the traceback. Tracebacks can be more readable if you put them in a pastebin (e.g., Gist or Hastebin), especially when communicating over IRC or email.
Turn on beets’ debug output (using the -v option: for example, beet -v import ...) and include that with your bug report. Look through this verbose output for any red flags that might point to the problem.
If you can, try installing the latest beets source code to see if the bug is fixed in an unreleased version. You can also look at the latest changelog entries for descriptions of the problem you’re seeing.
Try to narrow your problem down to something specific. Is a particular plugin causing the problem? (You can disable plugins to see whether the problem goes away.) Is a some music file or a single album leading to the crash? (Try importing individual albums to determine which one is causing the problem.) Is some entry in your configuration file causing it? Et cetera.
If you do narrow the problem down to a particular audio file or album, include it with your bug report so the developers can run tests.

If you’ve never reported a bug before, Mozilla has some well-written general guidelines for good bug reports.

…find the configuration file (config.yaml)?¶

You create this file yourself; beets just reads it. See Configuration.

…avoid using special characters in my filenames?¶

Use the %asciify{} function in your path formats. See Template Functions.

…point beets at a new music directory?¶

If you want to move your music from one directory to another, the best way is to let beets do it for you. First, edit your configuration and set the directory setting to the new place. Then, type beet move to have beets move all your files.

If you’ve already moved your music outside of beets, you have a few options:

Move the music back (with an ordinary mv) and then use the above steps.
Delete your database and re-create it from the new paths using beet import -AWC.
Resort to manually modifying the SQLite database (not recommended).

Why does beets…¶

…complain that it can’t find a match?¶

There are a number of possibilities:

First, make sure the album is in the MusicBrainz database. You can search on their site to make sure it’s cataloged there. (If not, anyone can edit MusicBrainz—so consider adding the data yourself.)
If the album in question is a multi-disc release, see the relevant FAQ answer above.
The music files’ metadata might be insufficient. Try using the “enter search” or “enter ID” options to help the matching process find the right MusicBrainz entry.
If you have a lot of files that are missing metadata, consider using acoustic fingerprinting or filename-based guesses for that music.

If none of these situations apply and you’re still having trouble tagging something, please file a bug report.

…appear to be missing some plugins?¶

Please make sure you’re using the latest version of beets—you might be using a version earlier than the one that introduced the plugin. In many cases, the plugin may be introduced in beets “trunk” (the latest source version) and might not be released yet. Take a look at the changelog to see which version added the plugin. (You can type beet version to check which version of beets you have installed.)

If you want to live on the bleeding edge and use the latest source version of beets, you can check out the source (see the relevant question).

To see the beets documentation for your version (and avoid confusion with new features in trunk), select your version from the menu in the sidebar.

…ignore control-C during an import?¶

Typing a ^C (control-C) control sequence will not halt beets’ multithreaded importer while it is waiting at a prompt for user input. Instead, hit “return” (dismissing the prompt) after typing ^C. Alternatively, just type a “b” for “aBort” at most prompts. Typing ^C will work if the importer interface is between prompts.

Also note that beets may take some time to quit after ^C is typed; it tries to clean up after itself briefly even when canceled.

(For developers: this is because the UI thread is blocking on input and cannot be interrupted by the main thread, which is trying to close all pipeline stages in the exception handler by setting a flag. There is no simple way to remedy this.)

…not change my ID3 tags?¶

Beets writes ID3v2.4 tags by default. Some software, including Windows (i.e., Windows Explorer and Windows Media Player) and id3lib/id3v2, don’t support v2.4 tags. When using 2.4-unaware software, it might look like the tags are unmodified or missing completely.

To enable ID3v2.3 tags, enable the id3v23 config option.

…complain that a file is “unreadable”?¶

Beets will log a message like “unreadable file: /path/to/music.mp3” when it encounters files that look like music files (according to their extension) but seem to be broken. Most of the time, this is because the file is corrupted. To check whether the file is intact, try opening it in another media player (e.g., VLC) to see whether it can read the file. You can also use specialized programs for checking file integrity—for example, type metaflac --list music.flac to check FLAC files.

If beets still complains about a file that seems to be valid, file a bug and we’ll look into it. There’s always a possibility that there’s a bug “upstream” in the Mutagen library used by beets, in which case we’ll forward the bug to that project’s tracker.

…seem to “hang” after an import finishes?¶

Probably not. Beets uses a multithreaded importer that overlaps many different activities: it can prompt you for decisions while, in the background, it talks to MusicBrainz and copies files. This means that, even after you make your last decision, there may be a backlog of files to be copied into place and tags to be written. (Plugin tasks, like looking up lyrics and genres, also run at this time.) If beets pauses after you see all the albums go by, have patience.

…put a bunch of underscores in my filenames?¶

When naming files, beets replaces certain characters to avoid causing problems on the filesystem. For example, leading dots can confusingly hide files on Unix and several non-alphanumeric characters are forbidden on Windows.

The replace config option controls which replacements are made. By default, beets makes filenames safe for all known platforms by replacing several patterns with underscores. This means that, even on Unix, filenames are made Windows-safe so that network filesystems (such as SMB) can be used safely.

Most notably, Windows forbids trailing dots, so a folder called “M.I.A.” will be rewritten to “M.I.A_” by default. Change the replace config if you don’t want this behavior and don’t need Windows-safe names.

…say “command not found”?¶

You need to put the beet program on your system’s search path. If you installed using pip, the command pip show -f beets can show you where beet was placed on your system. If you need help extending your $PATH, try this Super User answer.