Installation#

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

Using uv tool or pip#

We recommend installing with uv tool 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.

uv tool install beets

pipx install beets

pip install beets

pip install --user beets

If you don’t have uv installed, you can follow the uv installation instructions to get it set up.

Managing Plugins with uv tool#

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

Install beets with extras for built-in plugins:

uv tool install "beets[lyrics,lastgenre]"

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

uv tool install --force "beets[lyrics,lastgenre]"

Include additional packages in the beets environment (useful for third-party plugins):

uv tool install --force --with <package-name> beets

To upgrade beets and included packages:

uv tool 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.

Note

The classic Windows console (cmd.exe) does not display beets’ output (special characters and colors) correctly. For a usable experience, run beets in a terminal emulator such as Windows Terminal or cmder, or in a Unix-like shell such as Git Bash.

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 uv tool 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

  • Homebrew (formula): brew install beets

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