Installation#

Beets requires Python 3.10 or later. You can install it using pipx or pip.

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.

Managing Plugins with pipx#

When using pipx, you can install beets with built-in plugin dependencies using extras, inject third-party packages, and upgrade everything cleanly.

Install beets with extras for built-in plugins:

pipx install "beets[lyrics,lastgenre]"

If you already have beets installed, reinstall with a new set of extras:

pipx install --force "beets[lyrics,lastgenre]"

Inject additional packages into the beets environment (useful for third-party plugins):

pipx inject beets <package-name>

To upgrade beets and all injected packages:

pipx upgrade beets

Installation FAQ#

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.

Package Manager Installation#

Q: Can I install beets using my operating system’s built-in package manager?

We generally don’t recommend this route. OS package managers tend to ship outdated versions of beets, and installing third-party plugins into a system-managed environment ranges from awkward to impossible. You’ll have a much better time with pipx or pip as described above.

That said, if you know what you’re doing and prefer your system package manager, here are the options available:

  • Debian/Ubuntu (Debian, Ubuntu): apt-get install beets

  • Arch Linux (extra, AUR dev): pacman -S beets

  • Alpine Linux (package): apk add beets

  • Void Linux (package): xbps-install -S beets

  • Gentoo Linux: emerge beets (USE flags available for optional plugin deps)

  • FreeBSD (port): audio/beets

  • OpenBSD (port): pkg_add beets

  • Fedora (package): dnf install beets beets-plugins beets-doc

  • Solus: eopkg install beets

  • NixOS (package): nix-env -i beets

  • MacPorts: port install beets or port install beets-full (includes third-party plugins)