library

directory

plugins

include

pluginpath

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

ignore

ignore_hidden

replace

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 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

WARNING:

Default: _.

asciify_paths

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

threaded

format_item

It used to be named list_format_item.

format_album

It used to be named list_format_album.

sort_item

sort_album

sort_case_insensitive

original_date

artist_credit

per_disc_numbering

If you enable per_disc_numbering, you will likely want to change your Path Format Configuration also to include $disc before $track to make filenames sort correctly in album directories. For example, you might want to use a path format like this:

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

When this option is off (the default), even “pregap” hidden tracks are numbered from one, not zero, so other track numbers may appear to be bumped up by one. When it is on, the pregap track for each disc can be numbered zero.

aunique

The defaults look like this:

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

See aunique for more details.

terminal_encoding

clutter

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

max_filename_length

id3v23

va_name

color

NOTE:

colors

ui:
    color: yes
    colors:
        text_success: green
        text_warning: yellow
        text_error: red
        text_highlight: red
        text_highlight_minor: lightgray
        action_default: turquoise
        action: blue

Available colors: black, darkred, darkgreen, brown (darkyellow), darkblue, purple (darkmagenta), teal (darkcyan), lightgray, darkgray, red, green, yellow, blue, fuchsia (magenta), turquoise (cyan), white

write

copy

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).

move

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 is impossible.) 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.

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

link

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

It’s likely that you’ll also want to set write to no if you use this option to preserve the metadata on the linked files.

hardlink

As with symbolic links (see link, above), this will not work on Windows and you will want to set write to no. Otherwise, metadata on the original file will be modified.

reflink

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

incremental

incremental_skip_later

from_scratch

quiet

quiet_fallback

none_rec_action

timid

log

default_action

languages

detail

group_albums

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

Default: no.

autotag

Default: yes.

duplicate_action

bell

Default: no.

set_fields

set_fields:
    genre: '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.

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).

searchlimit

Default: 5.

extra_tags

musicbrainz:
    extra_tags: [year, catalognum, country, media, label]

This setting should improve the autotagger results if the metadata with the given tags match the metadata returned by MusicBrainz.

Note that the only tags supported by this setting are the ones listed in the above example.

Default: []

genres

max_rec

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:

preferred

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

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

match:
    required: year label catalognum country

No tags are required by default.

ignored_media

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

Default: yes.

ignore_video_tracks

Default: yes.

Environment Variable

Command-Line Option

Default Location

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.