Installation#

Beets requires Python 3.10 or later. You can install it using package managers, pipx, pip or by using package managers.

Using pipx or pip#

We recommend installing with pipx as it isolates beets and its dependencies from your system Python and other Python packages. This helps avoid dependency conflicts and keeps your system clean.

pipx install beets

pip install beets

pip install --user beets

If you don't have pipx installed, you can follow the instructions on the pipx installation page to get it set up.

Using a Package Manager#

Depending on your operating system, you may be able to install beets using a package manager. Here are some common options:

Attention

Package manager installations may not provide the latest version of beets.

Release cycles for package managers vary, and they may not always have the most recent version of beets. If you want the latest features and fixes, consider using pipx or pip as described above.

Additionally, installing external beets plugins may be surprisingly difficult when using a package manager.

  • On Debian or Ubuntu, depending on the version, beets is available as an official package (Debian details, Ubuntu details), so try typing: apt-get install beets. But the version in the repositories might lag behind, so make sure you read the right version of these docs. If you want the latest version, you can get everything you need to install with pip as described below by running: apt-get install python-dev python-pip

  • On Arch Linux, beets is in [extra], so just run pacman -S beets. (There's also a bleeding-edge dev package in the AUR, which will probably set your computer on fire.)

  • On Alpine Linux, beets is in the community repository and can be installed with apk add beets.

  • On Void Linux, beets is in the official repository and can be installed with xbps-install -S beets.

  • For Gentoo Linux, beets is in Portage as media-sound/beets. Just run emerge beets to install. There are several USE flags available for optional plugin dependencies.

  • On FreeBSD, there's a beets port at audio/beets.

  • On OpenBSD, there's a beets port can be installed with pkg_add beets.

  • On Fedora 22 or later, there's a DNF package you can install with sudo dnf install beets beets-plugins beets-doc.

  • On Solus, run eopkg install beets.

  • On NixOS, there's a package you can install with nix-env -i beets.

  • Using MacPorts, run port install beets or port install beets-full to include many third-party plugins.

Installation FAQ#

MacOS Installation#

Q: I'm getting permission errors on macOS. What should I do?

Due to System Integrity Protection on macOS 10.11+, you may need to install for your user only:

pip install --user beets

You might need to also add ~/Library/Python/3.x/bin to your $PATH.

Windows Installation#

Q: What's the process for installing on Windows?

Installing beets on Windows can be tricky. Following these steps might help you get it right:

  1. Install Python (check "Add Python to PATH" skip to 3)

  2. Ensure Python is in your PATH (add if needed):

    • Settings → System → About → Advanced system settings → Environment Variables

    • Edit "PATH" and add: ;C:Python39;C:Python39Scripts

    • Guide: [Adding Python to PATH](https://realpython.com/add-python-to-path/)

  3. Now install beets by running: pip install beets

  4. You're all set! Type beet version in a new command prompt to verify the installation.

Bonus: Windows Context Menu Integration

Windows users may also want to install a context menu item for importing files into beets. Download the beets.reg file and open it in a text file to make sure the paths to Python match your system. Then double-click the file add the necessary keys to your registry. You can then right-click a directory and choose "Import with beets".

ARM Installation#

Q: Can I run beets on a Raspberry Pi or other ARM device?

Yes, but with some considerations: Beets on ARM devices is not recommended for Linux novices. If you are comfortable with troubleshooting tools like pip, make, and binary dependencies (e.g. ffmpeg and ImageMagick), you will be fine. We have notes for ARM and an older ARM reference. Beets is generally developed on x86-64 based devices, and most plugins target that platform as well.