BEETSCONFIG(5)

✨ NAME ✨

beetsconfig — the beets configuration file 💖 (yes bestie, this is the BEETSCONFIG(5) page, we're doing the whole thing)

beets has an extremely extra configuration system that lets you customize basically every single aspect of how it operates. no cap. to configure beets, you make a file called config.yaml. where that file lives depends on your platform (and you can literally just type beet config -p to see the path on your system, slay):

• On Unix-like OSes, write ~/.config/beets/config.yaml.
• On Windows, use %APPDATA%\beets\config.yaml. this is usually in a directory like C:\Users\You\AppData\Roaming.
• On OS X, you can use either the Unix location or ~/Library/Application Support/beets/config.yaml.

You can launch your text editor to create or update your configuration by typing beet config -e. (See the config command for details.) It is also possible to customize the location of the configuration file and even use multiple layers of configuration. See Configuration Location, below. 🫶

The config file uses YAML syntax. you can use the full power of YAML, but most configuration options are simple key/value pairs. so your config file will look like this:

option: value
another_option: foo
bigger_option:
    key: value
    foo: bar

In YAML, you will need to use spaces (not tabs!) to indent some lines. if you have questions about more sophisticated syntax, take a look at the YAML documentation. 📝

The rest of this page enumerates the dizzying litany of configuration options available in beets. you might also want to see an example.

• Global Options
  • library
  • directory
  • tempfile_prefix
  • editor
  • create_backup_before_migrations
  • plugins
  • include
  • pluginpath
  • ignore
  • ignore_hidden
  • replace
  • path_sep_replace
  • asciify_paths
  • art_filename
  • threaded
  • format_item
  • format_album
  • sort_item
  • sort_album
  • sort_case_insensitive
  • original_date
  • overwrite_null
  • artist_credit
  • per_disc_numbering
  • aunique
  • sunique
  • terminal_encoding
  • clutter
  • max_filename_length
  • id3v23
  • va_name
• UI Options
  • color
  • colors
  • terminal_width
  • length_diff_thresh
  • import
• Importer Options
  • write
  • copy
  • move
  • link
  • hardlink
  • reflink
  • resume
  • incremental
  • incremental_skip_later
  • from_scratch
  • quiet
  • quiet_fallback
  • none_rec_action
  • timid
  • log
  • default_action
  • languages
  • ignored_alias_types
  • detail
  • group_albums
  • autotag
  • duplicate_keys
  • duplicate_action
  • duplicate_verbose_prompt
  • bell
  • set_fields
  • singleton_album_disambig
  • fix_ext_inplace
  • remux_mp3_in_wav
• Autotagger Matching Options
  • distance_weights
  • max_rec
  • preferred
  • ignored
  • required
  • ignored_media
  • ignore_data_tracks
  • ignore_video_tracks
• Path Format Configuration
• Configuration Location
  • Environment Variable
  • Command-Line Option
  • Default Location
• Example

---

🌍 GLOBAL OPTIONS 🌍

These options control beets' global operation. the whole vibe of the operation. 💅

📚 library

Path to the beets library file. by default, beets will use a file called library.db alongside your configuration file. bestie it just lives right next to the config, iconic.

🎧 directory

The directory to which files will be copied/moved when adding them to the library. Defaults to a folder called Music in your home directory. 🏠

🗂️ tempfile_prefix

The prefix used for temporary files when moving files across filesystems. If unset, temporary files use a leading dot (.). This can be changed when moving files to a Windows or Samba share, where a leading dot may cause the file to be treated as hidden. 👀

✍️ editor

The text editor to use when editing configuration files (e.g., via beet config -e). Overrides the $VISUAL and $EDITOR environment variables. If none of these are set, beets falls back to the platform default. Example:

editor: nano

💾 create_backup_before_migrations

Either yes or no, indicating whether a backup of the database file should be created before applying any pending schema migrations after a beets upgrade. The backup is only made when there are actually migrations to run. Defaults to yes. safety first, periodt. 🛟

🔌 plugins

A space-separated list of plugin module names to load. See Using Plugins.

📎 include

A space-separated list of extra configuration files to include. Filenames are relative to the directory containing config.yaml.

🧭 pluginpath

Directories to search for plugins. Each Python file or directory in a plugin path represents a plugin and should define a subclass of beets.plugins.BeetsPlugin. A plugin can then be loaded by adding the plugin name to the plugins configuration. The plugin path can either be a single string or a list of strings—so, if you have multiple paths, format them as a YAML list like so:

pluginpath:
    - /path/one
    - /path/two

🙈 ignore

A list of glob patterns specifying file and directory names to be ignored when importing. By default, this consists of .*, *~, System Volume Information, lost+found (i.e., beets ignores Unix-style hidden files, backup files, and directories that appears at the root of some Linux and Windows filesystems).

🫥 ignore_hidden

Either yes or no; whether to ignore hidden files when importing. On Windows, the "Hidden" property of files is used to detect whether or not a file is hidden. On OS X, the file's "IsHidden" flag is used to detect whether or not a file is hidden. On both OS X and other platforms (excluding Windows), files (and directories) starting with a dot are detected as hidden files.

🔁 replace

A set of regular expression/replacement pairs to be applied to all filenames created by beets. Typically, these replacements are used to avoid confusing problems or errors with the filesystem (for example, leading dots, which hide files on Unix, and trailing whitespace, which is illegal on Windows). To override these substitutions, specify a mapping from regular expression to replacement strings. For example, [xy]: z will make beets replace all instances of the characters x or y with the character z.

If you do change this value, be certain that you include at least enough substitutions to avoid causing errors on your operating system. Here are the default substitutions used by beets, which are sufficient to avoid unexpected behavior on all popular platforms:

replace:
    '[\\/]': _
    '^\.': _
    '[\x00-\x1f]': _
    '[<>:"\?\*\|]': _
    '\.$': _
    '\s+$': ''
    '^\s+': ''
    '^-': _

These substitutions remove forward and back slashes, leading dots, and control characters—all of which is a good idea on any OS. The fourth line removes the Windows "reserved characters" (useful even on Unix for compatibility with Windows-influenced network filesystems like Samba). Trailing dots and trailing whitespace, which can cause problems on Windows clients, are also removed. 🧹

When replacements other than the defaults are used, it is possible that they will increase the length of the path. In the scenario where this leads to a conflict with the maximum filename length, the default replacements will be used to resolve the conflict and beets will display a warning. ⚠️

Note that paths might contain special characters such as typographical quotes (" "). With the configuration above, those will not be replaced as they don't match the typewriter quote ("). To also strip these special characters, you can either add them to the replacement list or use the asciify_paths configuration option below.

🚧 path_sep_replace

A string that replaces the path separator (for example, the forward slash / on Linux and MacOS, and the backward slash \\ on Windows) when generating filenames with beets. This option is related to replace, but is distinct from it for technical reasons.

WARNING: Changing this option is potentially dangerous. For example, setting it to the actual path separator could create directories in unexpected locations. Use caution when changing it and always try it out on a small number of files before applying it to your whole library. 💀

Default: _.

🔤 asciify_paths

Convert all non-ASCII characters in paths to ASCII equivalents.

For example, if your path template for singletons is singletons/$title and the title of a track is "Café", then the track will be saved as singletons/Cafe.mp3. The changes take place before applying the replace configuration and are roughly equivalent to wrapping all your path templates in the %asciify{} template function.

This uses the unidecode module which is language agnostic, so some characters may be transliterated from a different language than expected. For example, Japanese kanji will usually use their Chinese readings. 😭

Default: no.

🖼️ art_filename

When importing album art, the name of the file (without extension) where the cover art image should be placed. This is a template string, so you can use any of the syntax available to Path Formats. Defaults to cover (i.e., images will be named cover.jpg or cover.png and placed in the album's directory). 🎀

🧵 threaded

Either yes or no, indicating whether the autotagger should use multiple threads. This makes things substantially faster by overlapping work: for example, it can copy files for one album in parallel with looking up data in MusicBrainz for a different album. You may want to disable this when debugging problems with the autotagger. Defaults to yes. multi-threading ate and left no crumbs 🔥

🧾 format_item

Format to use when listing individual items with the list command and other commands that need to print out items. Defaults to $artist - $album - $title. The -f command-line option overrides this setting.

It used to be named list_format_item.

💿 format_album

Format to use when listing albums with list and other commands. Defaults to $albumartist - $album. The -f command-line option overrides this setting.

It used to be named list_format_album.

🔀 sort_item

Default sort order to use when fetching items from the database. Defaults to artist+ album+ disc+ track+. Explicit sort orders override this default.

• sort_album — the default sort order beets uses when it's pulling albums out of the database. Defaults to albumartist+ album+. And heads up: if you explicitly set a sort order somewhere, that one wins over this default, no cap.
• sort_case_insensitive — yes or no, and it decides whether case gets ignored when sorting lexicographic fields. Set it to no and lowercase values get yeeted to the back after the uppercase ones (so you'd get Bar Qux foo 💀), while yes gives you the much more expected Bar foo Qux ✨. Default: yes.
• original_date — yes or no, controlling whether matched albums get their year, month, and day fields set to the release date of the original version of an album instead of the version you actually selected. Like, turn this on and year will always equal original_year and so on. Default: no.
• overwrite_null — okay so this one is named confusingly, the manpage said it not me 🙈. It tells beets which fields have meaningful null values. If an album or track field is in the corresponding list, then an existing value for that field in a database item can get overwritten with null. But by default? Null just means "this info is unavailable," so it won't overwrite anything that's already there. For example:

overwrite_null:
    album: ["albumid"]
    track: ["title", "date"]

• artist_credit — yes or no, deciding whether matched tracks and albums use the artist credit rather than the artist. Turn it on and artist will hold the artist exactly as credited on the release. 💅
• per_disc_numbering — a boolean that controls the track numbering style on multi-disc releases. By default (per_disc_numbering: no), tracks are numbered per-release, so the first track on the second disc is track number N+1, where N is however many tracks are on disc one. Flip this on and the first (non-pregap) track on every disc always gets track number 1. 🔥

If you enable per_disc_numbering, you'll probs also want to change your Path Format Configuration to include $disc before $track so filenames sort right in album directories. Like, maybe something like this:

paths:
    default: $albumartist/$album%aunique{}/$disc-$track $title

When this option is off (the default, bestie), even "pregap" hidden tracks are numbered from one, not zero, so other track numbers can look like they got bumped up by one. When it's on, the pregap track for each disc can be numbered zero.

• aunique — these options generate a string that's guaranteed to be unique among all the albums in your library that share the same set of keys. Iconic behavior honestly.

The defaults look like this:

aunique:
    keys: albumartist album
    disambiguators: albumtype year label catalognum albumdisambig releasegroupdisambig
    bracket: '[]'

See Album Disambiguation for the tea. 🫖

• sunique — like aunique up there but for albums, except this one controls generating a unique string to disambiguate singletons that share similar metadata.

The defaults look like this:

sunique:
    keys: artist title
    disambiguators: year trackdisambig
    bracket: '[]'

See Singleton Disambiguation for more.

• terminal_encoding — the text encoding, as known to Python, used for messages printed to standard output. It's also used to read messages from standard input. By default this gets figured out automatically from the locale environment variables. 🦋
• clutter — when beets imports all the files in a directory, it tries to remove the directory if it's empty. A directory counts as "empty" if it only contains files whose names match the glob patterns in clutter, which should be a list of strings. The default list is "Thumbs.DB" and ".DS_Store".

The importer only removes recursively searched subdirectories — the top-level directory you specify on the command line is never deleted. 🛑

• max_filename_length — the maximum number of characters in a filename, after which names get truncated. By default, beets tries to ask the filesystem what the correct maximum is.
• id3v23 — by default, beets writes MP3 tags using the ID3v2.4 standard, which is the latest version of ID3. Enable this option to use the older ID3v2.3 standard instead, which certain older software (looking at you, Windows Media Player) prefers. 👀
• va_name — sets the albumartist for various-artist compilations. Defaults to 'Various Artists' (the MusicBrainz standard). Affects other sources too, like the Discogs Plugin.

---

✨ UI OPTIONS ✨

The options that let you customize how the console interface actually looks. Glow-up time. 💅

• color — yes or no; whether to use color in console output. Turn this off if your terminal doesn't do ANSI colors.
• colors — the colors used all throughout the user interface. These only get used if the color option is set to yes. Peep the default configuration:

ui:
    colors:
        text_success: ['bold', 'green']
        text_warning: ['bold', 'yellow']
        text_error: ['bold', 'red']
        text_highlight: ['bold', 'red']
        text_highlight_minor: ['white']
        action_default: ['bold', 'cyan']
        action: ['bold', 'cyan']
        # New colors after UI overhaul
        text_faint: ['faint']
        import_path: ['bold', 'blue']
        import_path_items: ['bold', 'blue']
        changed: ['yellow']
        text_diff_added: ['bold', 'green']
        text_diff_removed: ['bold', 'red']
        action_description: ['white']

Available attributes:

Foreground colors

black, red, green, yellow, blue, magenta, cyan, white, bright_black, bright_red, bright_green, bright_yellow, bright_blue, bright_magenta, bright_cyan, bright_white

Background colors

bg_black, bg_red, bg_green, bg_yellow, bg_blue, bg_magenta, bg_cyan, bg_white, bg_bright_black, bg_bright_red, bg_bright_green, bg_bright_yellow, bg_bright_blue, bg_bright_magenta, bg_bright_cyan, bg_bright_white

Text styles

normal, bold, faint, italic, underline, blink_slow, blink_rapid, inverse, conceal, crossed_out

---

• terminal_width — controls line wrapping on non-Unix systems. On Unix systems the width of the terminal is detected automatically. If that fails, or if you're on a non-Unix system, the value you specify here is the fallback. Defaults to 80 characters:

ui:
    terminal_width: 80

• length_diff_thresh — beets compares the length of the imported track against the length the metadata source gives it. If any tracks differ by at least length_diff_thresh seconds, they get colored with text_highlight. Below that threshold, different track lengths get colored with text_highlight_minor. Just so you know: length_diff_thresh does not impact which releases get selected in autotagger matching or distance score calculation (see Autotagger Matching Options, distance_weights and colors):

ui:
    length_diff_thresh: 10.0

• import — when importing, beets reads several options to configure the visuals of the import dialogue. There are two layouts controlling how horizontal space and line wrapping get dealt with: column and newline. You can also configure the indentation of the respective elements of the import UI. Like, setting 2 for match_header will indent the very first block of a proposed match by two characters in the terminal:

ui:
    import:
        indentation:
            match_header: 2
            match_details: 2
            match_tracklist: 5
        layout: column

---

🌈 IMPORTER OPTIONS 🌈

The options that control the import command — they're indented under the import: key. So your config file section might look something like this:

import:
    write: yes
    copy: yes
    resume: no

These options live in this section:

• write — yes or no, controlling whether metadata (e.g., ID3) tags get written to files when you use beet import. Defaults to yes. The -w and -W command-line options override this setting.
• copy — yes or no, indicating whether to copy files into the library directory when using beet import. Defaults to yes. Can be overridden with the -c and -C command-line options.

Heads up: this option is ignored if move is enabled (i.e., beets can move or copy files, but it doesn't make sense to do both).

• move — yes or no, indicating whether to move files into the library directory when using beet import. Defaults to no.

The effect is similar to the copy option, but you end up with only one copy of the imported file. ("Moving" works even across filesystems; if necessary, beets will copy and then delete when a simple rename isn't possible.) Moving files can be risky — it's a good idea to keep a backup in case beets doesn't do what you expect with your files. 😭

When you're moving an archive during import, the archive gets removed if all its contents were successfully imported.

This option overrides copy, so enabling it will always move (and never copy) files. The -c switch to the beet import command still takes precedence, though.

• link — yes or no, indicating whether to use symbolic links instead of moving or copying files. (It conflicts with the move, copy and hardlink options.) Defaults to no.

This option only works on platforms that support symbolic links: i.e., Unixes. It will fail on Windows. 💀

You'll probs also want to set write to no if you use this option, to preserve the metadata on the linked files.

• hardlink — yes or no, indicating whether to use hard links instead of moving, copying, or symlinking files. (It conflicts with the move, copy, and link options.) Defaults to no.

Same deal as symbolic links (see link, above): this won't work on Windows and you'll want to set write to no. Otherwise, metadata on the original file will be modified. 🙈

• reflink — yes, no, or auto, indicating whether to use copy-on-write file clones (a.k.a. "reflinks") instead of copying or moving files. The auto option uses reflinks when possible and falls back to plain copying when necessary. Defaults to no.

This kind of clone is only available on certain filesystems: for example, btrfs and APFS. For more details on filesystem support, see the pyreflink documentation. Note that you need to install pyreflink, either through python -m pip install beets[reflink] or python -m pip install reflink.

The option is ignored if move is enabled (i.e., beets can move or copy files, but it doesn't make sense to do both).

resume 💖

okay so this one takes yes, no, or ask, and it decides whether an import that got interrupted gets picked back up again. yes = bestie we are ALWAYS resuming when it's possible, no questions asked. no = resuming is fully off the table, we're not doing that. ask (which is the default, btw) = when resuming is possible, the user gets prompted. and the -p and -P flags line up with the yes and no settings and they override this option. periodt.

incremental ✨

yes or no — controls whether imported directories get recorded, and whether those recorded directories get skipped. this is the config twin of the -i flag on beet import.

incremental_skip_later 🌸

yes or no, and it controls whether skipped directories get written into the incremental list. when it's yes, skipped directories won't be recorded, and beets will try to import them again later. when it's no, skipped directories will be recorded and skipped later on. defaults to no.

from_scratch 🦋

yes or no (default is no) — controls whether existing metadata gets thrown away when a match is applied. same energy as the --from-scratch flag on beet import. iykyk.

quiet 🤫

yes or no (default is no), controlling whether to ask the user for a manual decision when the importer genuinely can't tell how to proceed. this is the config bestie of the --quiet flag on beet import.

quiet_fallback 💅

either skip (the default) or asis — tells us what should happen in quiet mode (peep the -q flag to import, above) when there's no strong recommendation.

none_rec_action 👑

either ask (default), asis or skip. says what should go down during an interactive import session when there's no recommendation at all. super useful when you're only tryna process medium and strong recommendations interactively.

timid 🙈

yes or no, controlling whether the importer runs in timid mode, where it asks for confirmation on every autotagging match, even the ones that look super close. defaults to no. the -t command-line flag controls the same setting.

log 📝

specifies a filename where the importer's log should be kept. by default, no log is written. can be overridden with the -l flag to import.

default_action ⭐

one of apply, skip, asis, or none, indicating which option should be the default when you're selecting an action for a given match. this is the action that gets taken when you hit return without typing an option letter. default is apply.

languages 🌈

a list of locale names to search for preferred aliases. for example, setting this to en uses the transliterated artist name "Pyotr Ilyich Tchaikovsky" instead of the Cyrillic script for the composer's name when tagging from MusicBrainz. you can use a space-separated list of language abbreviations, like en jp es, to specify a preference order. defaults to an empty list, meaning no language is preferred.

the alias is used for artist name, track title, release group title and album title.

ignored_alias_types 💜

a list of alias types to be ignored when importing new items.

see the MusicBrainz Documentation for more info on aliases.

detail 🔍

whether the importer UI should show detailed information about each match it finds. when enabled, this mode prints out the title of every track, regardless of whether it matches the original metadata. (the default behavior only shows changes.) default: no.

group_albums 🎀

by default, the beets importer groups tracks into albums based on the directories they reside in. this option instead uses files' metadata to partition albums. enable it if you have directories that contain tracks from many albums mixed together. chaotic directories, we see you.

the --group-albums or -g option to the import command is equivalent, and the G interactive option invokes the same workflow.

default: no.

autotag 🔥

by default, the beets importer always attempts to autotag new music. if most of your collection consists of obscure music, you might be interested in disabling autotagging by setting this option to no. (you can re-enable it with the -a flag to the import command.)

default: yes.

duplicate_keys 👯

the fields used to find duplicates when importing. there are two sub-values here: album and item. each one is a list of field names; if an existing object (album or item) in the library matches the new object on all of these fields, the importer will consider it a duplicate.

default:

album: albumartist album
item: artist title

for MusicBrainz-tagged libraries, adding mb_albumid to the album keys distinguishes separate releases that have the same album artist and title:

album: albumartist album mb_albumid
item: artist title

all configured fields must match. albums with different MusicBrainz release IDs will therefore not be considered duplicates. an album without a MusicBrainz release ID will also not match an otherwise identical album that has one.

duplicate_action 💥

either skip, keep, remove, merge, upgrade or ask. controls how duplicates are treated in import task. skip means the new item (album or track) will be skipped; keep means keep both old and new items; remove means remove old item; merge means merge into one album; ask means the user should be prompted for the action each time. the default is ask.

upgrade compares each newly-imported track against any existing duplicate with the same duplicate_keys: a track only replaces its old counterpart if it has a higher bitrate, and tracks with no old counterpart are always added. the rest of the existing album is left untouched, and the kept tracks are added to that same album rather than a new one. if the import matches more than one existing album (e.g. two differently-encoded copies of the same release already in the library), only the album it overlaps with the most is upgraded; every other candidate album is left completely untouched, since a track can only ever be added to one album. when duplicate_action is ask, upgrade is one of the available interactive choices.

duplicate_verbose_prompt 🗣️

usually when duplicates are detected during import, info about the existing and the newly imported album is summarized. enabling this option also lists details on individual tracks. the format_item setting is applied, which would, considering the default, look like this:

This item is already in the library!
Old: 1 items, MP3, 320kbps, 5:56, 13.6 MiB
  Artist Name - Album Name - Third Track Title
New: 2 items, MP3, 320kbps, 7:18, 17.1 MiB
  Artist Name - Album Name - First Track Title
  Artist Name - Album Name - Second Track Title
[S]kip new, Merge all, Remove old, Keep all, Upgrade?

default: no.

bell 🔔

ring the terminal bell to get your attention when the importer needs your input.

default: no.

set_fields 🍓

a dictionary indicating fields to set to values for newly imported music. here's an example:

set_fields:
    genres: To Listen
    collection: Unordered

other field/value pairs supplied via the --set option on the command-line override any settings here for fields with the same name.

values support the same template syntax as beets' path formats.

fields are set on both the album and each individual track of the album. fields are persisted to the media files of each track.

default: {} (empty).

singleton_album_disambig 🧚

during singleton imports and if the metadata source provides it, album names are appended to the disambiguation string of matching track candidates. for example: The Artist - The Title (Discogs, Index 3, Track B1, [The Album]. this feature is currently supported by the Discogs Plugin and the Spotify Plugin.

default: yes.

fix_ext_inplace 🩹

the extension of each file is checked at import. if a file has no extension and its binary matches a music format, beets will look for a file with the same name and matching extension in the same directory. for example, when importing an mp3 file named asdf, beets look for asdf.mp3. if found, that file will be imported instead. otherwise, if fix_ext_inplace is yes, then the file will be renamed to contain the extension. if fix_ext_inplace is no, then the original will be left untouched and a copy with extension will be created in the same directory. this is only done if the user has ffprobe (bundled with FFmpeg).

default: no.

remux_mp3_in_wav 🎧

some WAV files contain MP3 audio streams (WAVE_FORMAT_MPEGLAYER3) rather than the standard PCM format. when this option is enabled, beets will automatically extract the MP3 stream into a proper .mp3 file during import, removing the WAV container. the original WAV file is deleted after successful extraction.

default: yes.

---

heads up bestie: that WAV gets deleted once extraction succeeds, so don't come crying to me if you wanted the container back. 🙈

✨ AUTOTAGGER MATCHING OPTIONS ✨

okay bestie, this is the part where you get to boss the autotagger around 💅 You can configure some aspects of the logic beets uses when automatically matching MusicBrainz results under the match: section. To control how tolerant the autotagger is of differences, use the strong_rec_thresh option, which reflects the distance threshold below which beets will make a “strong recommendation” that the metadata be used. Strong recommendations are accepted automatically (except in “timid” mode), so you can use this to make beets ask your opinion more or less often 🫶

The threshold is a distance value between 0.0 and 1.0, so you can think of it as the opposite of a similarity value. For example, if you want to automatically accept any matches above 90% similarity, use:

match:
    strong_rec_thresh: 0.10

The default strong recommendation threshold is 0.04.

The medium_rec_thresh and rec_gap_thresh options work similarly. When a match is below the medium recommendation threshold or the distance between it and the next-best match is above the gap threshold, the importer will suggest that match but not automatically confirm it. Otherwise, you’ll see a list of options to choose from 👑

distance_weights

The distance_weights option lets you customize how much each field contributes to the overall distance score when matching albums and tracks. Higher weights mean that differences in that field are penalized more heavily, making them more important in the matching decision 🔥

The defaults are:

match:
    distance_weights:
        data_source: 2.0
        artist: 3.0
        album: 3.0
        media: 1.0
        mediums: 1.0
        year: 1.0
        country: 0.5
        label: 0.5
        catalognum: 0.5
        albumdisambig: 0.5
        album_id: 5.0
        tracks: 2.0
        missing_tracks: 0.9
        unmatched_tracks: 0.6
        track_title: 3.0
        track_artist: 2.0
        track_index: 1.0
        track_length: 2.0
        track_id: 5.0
        medium: 1.0

For example, if you don’t care as much about matching the exact release year, you can reduce its weight:

match:
    distance_weights:
        year: 0.1

You only need to specify the fields you want to override; unspecified fields keep their default weights 💖

max_rec

As mentioned above, autotagger matches have recommendations that control how the UI behaves for a certain quality of match. The recommendation for a certain match is based on the overall distance calculation. But you can also control the recommendation when a specific distance penalty is applied by defining maximum recommendations for each field 💅

To define maxima, use keys under max_rec: in the match section. The defaults are “medium” for missing and unmatched tracks and “strong” (i.e., no maximum) for everything else:

match:
    max_rec:
        missing_tracks: medium
        unmatched_tracks: medium

If a recommendation is higher than the configured maximum and the indicated penalty is applied, the recommendation is downgraded. The setting for each field can be one of none, low, medium or strong. When the maximum recommendation is strong, no “downgrading” occurs. The available penalty names here are:

• data_source
• artist
• album
• media
• mediums
• year
• country
• label
• catalognum
• albumdisambig
• album_id
• tracks
• missing_tracks
• unmatched_tracks
• track_title
• track_artist
• track_index
• track_length
• track_id

preferred

In addition to comparing the tagged metadata with the match metadata for similarity, you can also specify an ordered list of preferred countries and media types 🌈

A distance penalty will be applied if the country or media type from the match metadata doesn’t match. The specified values are preferred in descending order (i.e., the first item will be most preferred). Each item may be a regular expression, and will be matched case insensitively. The number of media will be stripped when matching preferred media (e.g. “2x” in “2xCD”).

You can also tell the autotagger to prefer matches that have a release year closest to the original year for an album 🎀

Here’s an example:

match:
    preferred:
        countries: ['US', 'GB|UK']
        media: ['CD', 'Digital Media|File']
        original_year: yes

By default, none of these options are enabled 🙈

ignored

You can completely avoid matches that have certain penalties applied by adding the penalty name to the ignored setting:

match:
    ignored: missing_tracks unmatched_tracks

The available penalties are the same as those for the max_rec setting.

For example, setting ignored: missing_tracks will skip any album matches where your audio files are missing some of the tracks. The importer will not attempt to display these matches. It does not ignore the fact that the album is missing tracks, which would allow these matches to apply more easily. To do that, you’ll want to adjust the penalty for missing tracks 👀

required

You can avoid matches that lack certain required information. Add the tags you want to enforce to the required setting:

match:
    required: year label catalognum country

No tags are required by default ✨

ignored_media

A list of media (i.e., formats) in metadata databases to ignore when matching music. You can use this to ignore all media that usually contain video instead of audio, for example:

match:
    ignored_media: ['Data CD', 'DVD', 'DVD-Video', 'Blu-ray', 'HD-DVD',
                    'VCD', 'SVCD', 'UMD', 'VHS']

No formats are ignored by default 💜

ignore_data_tracks

By default, audio files contained in data tracks within a release are included in the album’s tracklist. If you want them to be included, set it no.

Default: yes.

ignore_video_tracks

By default, video tracks within a release will be ignored. If you want them to be included (for example if you would like to track the audio-only versions of the video tracks), set it to no.

Default: yes.

---

🌸 PATH FORMAT CONFIGURATION 🌸

You can also configure the directory hierarchy beets uses to store music. These settings appear under the paths: key. Each string is a template string that can refer to metadata fields like $artist or $title. The filename extension is added automatically. At the moment, you can specify three special paths: default for most releases, comp for “various artist” releases with no dominant artist, and singleton for non-album tracks. The defaults look like this:

paths:
    default: $albumartist/$album%aunique{}/$track $title
    singleton: Non-Album/$artist/$title
    comp: Compilations/$album%aunique{}/$track $title

Note the use of $albumartist instead of $artist; this ensures that albums will be well-organized 🧚 For more about these format strings, see Path Formats. The aunique{} function ensures that identically-named albums are placed in different directories; see Album Disambiguation for details.

In addition to default, comp, and singleton, you can condition path queries based on beets queries (see Queries). This means that a config file like this:

paths:
    albumtype:soundtrack: Soundtracks/$album/$track $title

will place soundtrack albums in a separate directory 🎬 The queries are tested in the order they appear in the configuration file, meaning that if an item matches multiple queries, beets will use the path format for the first matching query. Queries on multi-value fields, such as genres, match each individual value, so an exact string query like genres:=Classical can match an item whose genres are Classical and Baroque without also matching Neoclassical 💅

Note that the special singleton and comp path format conditions are, in fact, just shorthand for the explicit queries singleton:true and comp:true. In contrast, default is special and has no query equivalent: the default format is only used if no queries match ⭐

---

🦋 CONFIGURATION LOCATION 🦋

The beets configuration file is usually located in a standard location that depends on your OS, but there are a couple of ways you can tell beets where to look 👑

Environment Variable

First, you can set the BEETSDIR environment variable to a directory containing a config.yaml file. This replaces your configuration in the default location. This also affects where auxiliary files, like the library database, are stored by default (that’s where relative paths are resolved to). This environment variable is useful if you need to manage multiple beets libraries with separate configurations 💖

Command-Line Option

Alternatively, you can use the --config command-line option to indicate a YAML file containing options that will then be merged with your existing options (from BEETSDIR or the default locations). This is useful if you want to keep your configuration mostly the same but modify a few options as a batch. For example, you might have different strategies for importing files, each with a different set of importer options 🎀

Default Location

In the absence of a BEETSDIR variable, beets searches a few places for your configuration, depending on the platform:

• On Unix platforms, including OS X: ~/.config/beets and then $XDG_CONFIG_DIR/beets, if the environment variable is set.
• On OS X, we also search ~/Library/Application Support/beets before the Unixy locations.
• On Windows: ~\AppData\Roaming\beets, and then %APPDATA%\beets, if the environment variable is set.

Beets uses the first directory in your platform’s list that contains config.yaml. If no config file exists, the last path in the list is used 🌈

---

💜 EXAMPLE 💜

Here’s an example file:

directory: /var/mp3
import:
    copy: yes
    write: yes
    log: beetslog.txt
art_filename: albumart
plugins: bpd
pluginpath: ~/beets/myplugins
ui:
    color: yes

paths:
    default: %first{$genres}/$albumartist/$album/$track $title
    singleton: Singletons/$artist - $title
    comp: %first{$genres}/$album/$track $title
    albumtype:soundtrack: Soundtracks/$album/$track $title

---

⭐ SEE ALSO ⭐

• https://beets.readthedocs.org/
• beet(1)

---

👑 AUTHOR 👑

Adrian Sampson

💖 COPYRIGHT 💖

2016, Adrian Sampson

---

and that's a wrap bestie!! 🫶 this was beetsconfig(5), version 2.14, dated Sep 17, 2026 — go forth and tag your music immaculately, no cap 💅✨🍓