|
| 1 | +Installation |
| 2 | +============ |
| 3 | + |
| 4 | +Beets requires `Python 3.9 or later`_. You can install it using package |
| 5 | +managers, pipx_, pip_ or by using package managers. |
| 6 | + |
| 7 | +.. _python 3.9 or later: https://python.org/download/ |
| 8 | + |
| 9 | +Using ``pipx`` or ``pip`` |
| 10 | +------------------------- |
| 11 | + |
| 12 | +We recommend installing with pipx_ as it isolates beets and its dependencies |
| 13 | +from your system Python and other Python packages. This helps avoid dependency |
| 14 | +conflicts and keeps your system clean. |
| 15 | + |
| 16 | +.. <!-- start-quick-install --> |
| 17 | +
|
| 18 | +.. tab-set:: |
| 19 | + |
| 20 | + .. tab-item:: pipx |
| 21 | + |
| 22 | + .. code-block:: console |
| 23 | +
|
| 24 | + pipx install beets |
| 25 | +
|
| 26 | + .. tab-item:: pip |
| 27 | + |
| 28 | + .. code-block:: console |
| 29 | +
|
| 30 | + pip install beets |
| 31 | +
|
| 32 | + .. tab-item:: pip (user install) |
| 33 | + |
| 34 | + .. code-block:: console |
| 35 | +
|
| 36 | + pip install --user beets |
| 37 | +
|
| 38 | +.. <!-- end-quick-install --> |
| 39 | +
|
| 40 | +If you don't have pipx_ installed, you can follow the instructions on the `pipx |
| 41 | +installation page`_ to get it set up. |
| 42 | + |
| 43 | +.. _pip: https://pip.pypa.io/en/ |
| 44 | + |
| 45 | +.. _pipx: https://pipx.pypa.io/stable |
| 46 | + |
| 47 | +.. _pipx installation page: https://pipx.pypa.io/stable/installation/ |
| 48 | + |
| 49 | +Using a Package Manager |
| 50 | +----------------------- |
| 51 | + |
| 52 | +Depending on your operating system, you may be able to install beets using a |
| 53 | +package manager. Here are some common options: |
| 54 | + |
| 55 | +.. attention:: |
| 56 | + |
| 57 | + Package manager installations may not provide the latest version of beets. |
| 58 | + |
| 59 | + Release cycles for package managers vary, and they may not always have the |
| 60 | + most recent version of beets. If you want the latest features and fixes, |
| 61 | + consider using pipx_ or pip_ as described above. |
| 62 | + |
| 63 | + Additionally, installing external beets plugins may be surprisingly |
| 64 | + difficult when using a package manager. |
| 65 | + |
| 66 | +- On **Debian or Ubuntu**, depending on the version, beets is available as an |
| 67 | + official package (`Debian details`_, `Ubuntu details`_), so try typing: |
| 68 | + ``apt-get install beets``. But the version in the repositories might lag |
| 69 | + behind, so make sure you read the right version of these docs. If you want the |
| 70 | + latest version, you can get everything you need to install with pip as |
| 71 | + described below by running: ``apt-get install python-dev python-pip`` |
| 72 | +- On **Arch Linux**, `beets is in [extra] <arch extra_>`_, so just run ``pacman |
| 73 | + -S beets``. (There's also a bleeding-edge `dev package <aur_>`_ in the AUR, |
| 74 | + which will probably set your computer on fire.) |
| 75 | +- On **Alpine Linux**, `beets is in the community repository <alpine package_>`_ |
| 76 | + and can be installed with ``apk add beets``. |
| 77 | +- On **Void Linux**, `beets is in the official repository <void package_>`_ and |
| 78 | + can be installed with ``xbps-install -S beets``. |
| 79 | +- For **Gentoo Linux**, beets is in Portage as ``media-sound/beets``. Just run |
| 80 | + ``emerge beets`` to install. There are several USE flags available for |
| 81 | + optional plugin dependencies. |
| 82 | +- On **FreeBSD**, there's a `beets port <freebsd_>`_ at ``audio/beets``. |
| 83 | +- On **OpenBSD**, there's a `beets port <openbsd_>`_ can be installed with |
| 84 | + ``pkg_add beets``. |
| 85 | +- On **Fedora** 22 or later, there's a `DNF package`_ you can install with |
| 86 | + ``sudo dnf install beets beets-plugins beets-doc``. |
| 87 | +- On **Solus**, run ``eopkg install beets``. |
| 88 | +- On **NixOS**, there's a `package <nixos_>`_ you can install with ``nix-env -i |
| 89 | + beets``. |
| 90 | +- Using **MacPorts**, run ``port install beets`` or ``port install beets-full`` |
| 91 | + to include many third-party plugins. |
| 92 | + |
| 93 | +.. _alpine package: https://pkgs.alpinelinux.org/package/edge/community/x86_64/beets |
| 94 | + |
| 95 | +.. _arch extra: https://archlinux.org/packages/extra/any/beets/ |
| 96 | + |
| 97 | +.. _aur: https://aur.archlinux.org/packages/beets-git/ |
| 98 | + |
| 99 | +.. _debian details: https://tracker.debian.org/pkg/beets |
| 100 | + |
| 101 | +.. _dnf package: https://packages.fedoraproject.org/pkgs/beets/ |
| 102 | + |
| 103 | +.. _freebsd: http://portsmon.freebsd.org/portoverview.py?category=audio&portname=beets |
| 104 | + |
| 105 | +.. _nixos: https://github.com/NixOS/nixpkgs/tree/master/pkgs/tools/audio/beets |
| 106 | + |
| 107 | +.. _openbsd: http://openports.se/audio/beets |
| 108 | + |
| 109 | +.. _ubuntu details: https://launchpad.net/ubuntu/+source/beets |
| 110 | + |
| 111 | +.. _void package: https://github.com/void-linux/void-packages/tree/master/srcpkgs/beets |
| 112 | + |
| 113 | +Installation FAQ |
| 114 | +---------------- |
| 115 | + |
| 116 | +MacOS Installation |
| 117 | +~~~~~~~~~~~~~~~~~~ |
| 118 | + |
| 119 | +**Q: I'm getting permission errors on macOS. What should I do?** |
| 120 | + |
| 121 | +Due to System Integrity Protection on macOS 10.11+, you may need to install for |
| 122 | +your user only: |
| 123 | + |
| 124 | +.. code-block:: console |
| 125 | +
|
| 126 | + pip install --user beets |
| 127 | +
|
| 128 | +You might need to also add ``~/Library/Python/3.x/bin`` to your ``$PATH``. |
| 129 | + |
| 130 | +Windows Installation |
| 131 | +~~~~~~~~~~~~~~~~~~~~ |
| 132 | + |
| 133 | +**Q: What's the process for installing on Windows?** |
| 134 | + |
| 135 | +Installing beets on Windows can be tricky. Following these steps might help you |
| 136 | +get it right: |
| 137 | + |
| 138 | +1. `Install Python`_ (check "Add Python to PATH" skip to 3) |
| 139 | +2. Ensure Python is in your ``PATH`` (add if needed): |
| 140 | + |
| 141 | + - Settings → System → About → Advanced system settings → Environment |
| 142 | + Variables |
| 143 | + - Edit "PATH" and add: `;C:\Python39;C:\Python39\Scripts` |
| 144 | + - *Guide: [Adding Python to |
| 145 | + PATH](https://realpython.com/add-python-to-path/)* |
| 146 | + |
| 147 | +3. Now install beets by running: ``pip install beets`` |
| 148 | +4. You're all set! Type ``beet version`` in a new command prompt to verify the |
| 149 | + installation. |
| 150 | + |
| 151 | +**Bonus: Windows Context Menu Integration** |
| 152 | + |
| 153 | +Windows users may also want to install a context menu item for importing files |
| 154 | +into beets. Download the beets.reg_ file and open it in a text file to make sure |
| 155 | +the paths to Python match your system. Then double-click the file add the |
| 156 | +necessary keys to your registry. You can then right-click a directory and choose |
| 157 | +"Import with beets". |
| 158 | + |
| 159 | +.. _beets.reg: https://github.com/beetbox/beets/blob/master/extra/beets.reg |
| 160 | + |
| 161 | +.. _install pip: https://pip.pypa.io/en/stable/installing/ |
| 162 | + |
| 163 | +.. _install python: https://python.org/download/ |
| 164 | + |
| 165 | +ARM Installation |
| 166 | +~~~~~~~~~~~~~~~~ |
| 167 | + |
| 168 | +**Q: Can I run beets on a Raspberry Pi or other ARM device?** |
| 169 | + |
| 170 | +Yes, but with some considerations: Beets on ARM devices is not recommended for |
| 171 | +Linux novices. If you are comfortable with troubleshooting tools like ``pip``, |
| 172 | +``make``, and binary dependencies (e.g. ``ffmpeg`` and ``ImageMagick``), you |
| 173 | +will be fine. We have `notes for ARM`_ and an `older ARM reference`_. Beets is |
| 174 | +generally developed on x86-64 based devices, and most plugins target that |
| 175 | +platform as well. |
| 176 | + |
| 177 | +.. _notes for arm: https://github.com/beetbox/beets/discussions/4910 |
| 178 | + |
| 179 | +.. _older arm reference: https://discourse.beets.io/t/diary-of-beets-on-arm-odroid-hc4-armbian/1993 |
0 commit comments