Skip to main content
`Ctrl`+`K`

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

uv tool

    uv tool install beets

pipx

    pipx install beets

pip

    pip install beets

pip (user install)

    pip install --user beets

Need more information?

Having trouble with the commands above? Looking for information how to install plugins and keep Beets updated? See the complete installation guide for:

- Managing plugins with uv tool

- OS-specific installation notes

- Package manager options

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

     Copy Files (Default)

     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

     Move Files

     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

     Use Existing Structure

     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

     Read-Only Mode

     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.

Autotag (Recommended)

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.

Quick Import

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.