Skip to main content
`Ctrl`+`K`

# Installation

Beets requires Python 3.9 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

    pipx install beets

pip

    pip install beets

pip (user install)

    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.