Guide · Open source
How to use beets: install it and tag your music library
Updated · written with AI from the project's own documentation and checked against our catalogue data
beets is an open-source, command-line tool for managing a music collection. It uses the MusicBrainz database to fill in and correct tags such as artist, album and track names, and it can organize files into folders based on those tags. This guide explains what beets is good for, what you need before installing it, and how to get started, so you can decide whether it fits your library.
beetsbeetbox/beets · ★ 15.9k · MIT Install options & downloads Quick start
- 1Check that Python 3 is installed. beets requires Python 3. Confirm you have it on your system before you start.
- 2Install beets with a package manager. The project is distributed through a package manager. Follow the installation guidance at beets.io for the exact command for your system.
- 3Clone the repository if you want the source. Run git clone https://github.com/beetbox/beets.git to download the source code from GitHub.
- 4Read the documentation and configure. Review the project documentation at beets.io and set up your configuration files before changing any music files.
- 5Back up and test on a small folder. Before running tag or organization changes on your full collection, back up your files and try the workflow on a small set first.
What beets does
beets is a command-line tool for managing a music collection. Its main job is to use the MusicBrainz database to fill in and correct tags such as artist, album and track names.
Once tags are consistent, beets can organize files into folders based on those tags. People use it to keep large, messy music libraries consistent without tagging each file by hand.
- Fills in missing tags from MusicBrainz data
- Corrects inconsistent artist, album and track names
- Organizes files into folders based on their tags
What you need before you install beets
The main prerequisite is Python 3. beets is written in Python, and the project is distributed through a package manager.
beets is comfortable for people who work in a terminal. Setup involves a command-line workflow, so if you are not comfortable running commands or editing configuration files, expect a learning curve.
- Python 3 installed on your system
- Comfort using a terminal
- A music collection with tags you want to clean up
Get the beets source code
The project README gives this command to clone the repository. Run it in the folder where you want the source to live.
The homepage at beets.io is the project's home. Check it for the current installation guidance, since the README available for this page did not include full setup instructions.
git clone https://github.com/beetbox/beets.gitCustomize your library workflow
beets is a good fit for Python users who want to customize how their library is handled. Because it is an open-source Python project, you can read the code and adapt it to your needs.
Customization is done through configuration files, so plan to spend some time reading the project documentation before making changes.
- Read the project documentation at beets.io before editing configuration
- Keep a backup of your music library before running any tag or file changes
Know when beets is not the right tool
beets is a command-line manager. It is not a graphical music player or a streaming app, and the material available for this guide does not describe a graphical interface.
If you want a visual tagger or a player, look at the comparable projects listed below instead.
- Graphical music players or streaming apps: choose a different type of product
- Users who do not want to install Python tools or edit configuration: a GUI tagger may be easier
What people use it for
- Filling in missing artist, album and track tags across a large collection
- Correcting inconsistent tag spelling so albums group together properly
- Organizing a messy download folder into a consistent folder structure based on tags
- Building a customized, scriptable library workflow as a Python user
Frequently asked questions
Is beets free to use?
Yes. beets is released under the MIT licence, which is a permissive open-source licence. The source is hosted on GitHub at beetbox/beets.
What do I need to install beets?
You need Python 3. beets is installed through a package manager, and the project homepage at beets.io has the current installation guidance.
Is beets a graphical app?
No. beets is a command-line tool for managing a music collection. The material available for this guide does not describe a graphical interface or a music player.
What is beets used for?
It is used to fill in and correct tags such as artist, album and track names using the MusicBrainz database, and to organize files into folders based on those tags.
What are the alternatives to beets?
The comparable projects listed for this tool are MusicBrainz Picard, Mp3tag and Beatport Tagger. The available material does not include a feature-by-feature comparison, so check each project's documentation for differences.
Where can I get help if beets does not work?
The available material does not include troubleshooting details. Start with the project homepage at beets.io and the repository at github.com/beetbox/beets.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
beets suits people with large music collections that have inconsistent or missing tags, especially if they are comfortable in a terminal and want MusicBrainz-based metadata applied automatically. Choose a different tool if you want a graphical player or streaming app, or if you prefer not to install Python tools and edit configuration files.
Install options & downloads