Skip to main content
`Ctrl`+`K`

# 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

    uv tool install beets

pipx

    pipx install beets

pip

    pip install beets

pip (user install)

    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)