Getting Started#

Welcome to beets! This guide will help get started with improving and organizing your music collection.

Quick Installation#

Beets is distributed via PyPI and can be installed by most users with a single command:

pipx install beets

pip install beets

pip install --user beets

Need more installation options?

Having trouble with the commands above? Looking for package manager instructions? See the complete installation guide for:

  • Operating system specific instructions

  • Package manager options

  • Troubleshooting help

Basic Configuration#

Before using beets, you'll need a configuration file. This YAML file tells beets where to store your music and how to organize it.

While beets is highly configurable, you only need a few basic settings to get started.

  1. Open the config file:
    beet config -e

    This creates the file (if needed) and opens it in your default editor. You can also find its location with beet config -p.

  2. Add required settings:

    In the config file, set the directory option to the path where you want beets to store your music files. Set the library option to the path where you want beets to store its database file.

    directory: ~/music
library: ~/data/musiclibrary.db
  3. Choose your import style (pick one):

    Beets offers flexible import strategies to match your workflow. Choose one of the following approaches and put one of the following in your config file:

    This is the default configuration and assumes you want to start a new organized music folder (inside directory above). During import we will copy cleaned-up music into that empty folder.

    import:
    copy: yes    # Copy files to new location

    Start with a new empty directory, but move new music in instead of copying it (saving disk space).

    import:
    move: yes    # Move files to new location

    Keep your current directory structure; importing should never move or copy files but instead just correct the tags on music. Make sure to point directory at the place where your music is currently stored.

    import:
    copy: no     # Use files in place

    Keep everything exactly as-is; only track metadata in database. (Corrected tags will still be stored in beets' database, and you can use them to do renaming or tag changes later.)

    import:
    copy: no     # Use files in place
    write: no    # Don't modify tags
  4. Add customization via plugins (optional):

    Beets comes with many plugins that extend its functionality. You can enable plugins by adding a plugins section to your config file.

    We recommend adding at least one Autotagger Plugin to help with fetching metadata during import. For getting started, MusicBrainz is a good choice.

    plugins:
  - musicbrainz  # Example plugin for fetching metadata
  - ... other plugins you want ...

    You can find a list of available plugins in the plugins index.

To validate that you've set up your configuration and it is valid YAML, you can type beet version to see a list of enabled plugins or beet config to get a complete listing of your current configuration.

Minimal configuration

Here's a sample configuration file that includes the settings mentioned above:

directory: ~/music
library: ~/data/musiclibrary.db

import:
    move: yes    # Move files to new location
    # copy: no   # Use files in place
    # write: no  # Don't modify tags

plugins:
  - musicbrainz  # Example plugin for fetching metadata
  # - ... other plugins you want ...

You can copy and paste this into your config file and modify it as needed.

Ready for more?

For a complete reference of all configuration options, see the configuration reference.

Importing Your Music#

Now you're ready to import your music into beets!

Important

Importing can modify and move your music files. Make sure you have a recent backup before proceeding.

Choose Your Import Method#

There are two good ways to bring your existing library into beets database.

This method uses beets' autotagger to find canonical metadata for every album you import. It may take a while, especially for large libraries, and it's an interactive process. But it ensures all your songs' tags are exactly right from the get-go.

beet import /a/chunk/of/my/library

Warning

The point about speed bears repeating: using the autotagger on a large library can take a very long time, and it's an interactive process. So set aside a good chunk of time if you're going to go that route.

We also recommend importing smaller batches of music at a time (e.g., a few albums) to make the process more manageable. For more on the interactive tagging process, see Using the Auto-Tagger.

This method quickly brings all your files with all their current metadata into beets' database without any changes. It's really fast, but it doesn't clean up or correct any tags.

To use this method, run:

beet import --noautotag /my/huge/mp3/library

The --noautotag / -A flag skips autotagging and uses your files' current metadata.

More Import Options

The beet import command has many options to customize its behavior. For a full list, type beet help import or see the import command reference.

Adding More Music Later#

When you acquire new music, use the same beet import command to add it to your library:

beet import ~/new_totally_not_ripped_album

This will apply the same autotagging process to your new additions. For alternative import behaviors, consult the options mentioned above.

Seeing Your Music#

Once you've imported music into beets, you'll want to explore and query your library. Beets provides several commands for searching, browsing, and getting statistics about your collection.

Basic Searching#

The beet list command (shortened to beet ls) lets you search your music library using query string similar to web searches:

$ beet ls the magnetic fields
The Magnetic Fields - Distortion - Three-Way
The Magnetic Fields - Dist
The Magnetic Fields - Distortion - Old Fools

$ beet ls hissing gronlandic
of Montreal - Hissing Fauna, Are You the Destroyer? - Gronlandic Edit

$ beet ls bird
The Knife - The Knife - Bird
The Mae Shi - Terrorbird - Revelation Six

By default, search terms match against common attributes of songs, and multiple terms are combined with AND logic (a track must match all criteria).

Searching Specific Fields#

To narrow a search term to a particular metadata field, prefix the term with the field name followed by a colon. For example, album:bird searches for "bird" only in the "album" field of your songs. For more details, see Queries.

$ beet ls album:bird
The Mae Shi - Terrorbird - Revelation Six

This searches only the album field for the term bird.

Searching for Albums#

The beet list command also has an -a option, which searches for albums instead of songs:

$ beet ls -a forever
Bon Iver - For Emma, Forever Ago
Freezepop - Freezepop Forever

Custom Output Formatting#

There's also an -f option (for format) that lets you specify what gets displayed in the results of a search:

$ beet ls -a forever -f "[$format] $album ($year) - $artist - $title"
[MP3] For Emma, Forever Ago (2009) - Bon Iver - Flume
[AAC] Freezepop Forever (2011) - Freezepop - Harebrained Scheme

In the format string, field references like $format, $year, $album, etc., are replaced with data from each result.

Available fields for formatting

To see all available fields you can use in custom formats, run:

beet fields

This will display a comprehensive list of metadata fields available for your music.

Library Statistics#

Beets can also show you statistics about your music collection:

$ beet stats
Tracks: 13019
Total time: 4.9 weeks
Total size: 71.1 GB
Artists: 548
Albums: 1094

Ready for more advanced queries?

The beet list command has many additional options for sorting, limiting results, and more complex queries. For a complete reference, run:

beet help list

Or see the list command reference.

Keep Playing#

Congratulations! You've now mastered the basics of beets. But this is only the beginning, beets has many more powerful features to explore.

Continue Your Learning Journey#

I was there to push people beyond what's expected of them.

Advanced Techniques

Explore sophisticated beets workflows including:

  • Advanced tagging strategies

  • Complex import scenarios

  • Custom metadata management

  • Workflow automation

Advanced Awesomeness
Command Reference

Comprehensive guide to all beets commands:

  • Complete command syntax

  • All available options

  • Usage examples

  • Important operations like deleting music

Command-Line Interface
Plugin Ecosystem

Discover beets' true power through plugins:

  • Metadata fetching from multiple sources

  • Audio analysis and processing

  • Streaming service integration

  • Custom export formats

Plugins
Illustrated Walkthrough

Visual, step-by-step guide covering:

  • Real-world import examples

  • Screenshots of interactive tagging

  • Common workflow patterns

  • Troubleshooting tips

https://beets.io/blog/walkthrough.html

Need Help?

Remember you can always use beet help to see all available commands, or beet help [command] for detailed help on specific commands.

Join the Community#

We'd love to hear about your experience with beets!

Discussion Board

  • Ask questions

  • Share tips and tricks

  • Discuss feature ideas

  • Get help from other users

https://github.com/beetbox/beets/discussions
Developer Resources

  • Contribute code

  • Report issues

  • Review pull requests

  • Join development discussions

For Developers

Found a Bug?

If you encounter any issues, please report them on our GitHub Issues page.