From 3ff93c2eebd6ec324412669685c4d98bac05eb6e Mon Sep 17 00:00:00 2001 From: Andrey Mivrenik Date: Tue, 17 Mar 2026 17:50:22 +0200 Subject: [PATCH] docs(installation): Update installation guide --- docs/changelog.rst | 2 + docs/guides/installation.rst | 119 ++++++++++++++++++++--------------- 2 files changed, 69 insertions(+), 52 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 3d7b864ac..0306e017d 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -84,6 +84,8 @@ Other changes :py:meth:`~beets.metadata_plugins.SearchApiMetadataSourcePlugin.get_search_response`. - :doc:`guides/installation`: Remove redundant macOS section from the installation guide. :bug:`5993` +- :doc:`guides/installation`: Update installation guide to document plugin + management with pipx and move package manager instructions to the FAQ. 2.7.1 (March 08, 2026) ---------------------- diff --git a/docs/guides/installation.rst b/docs/guides/installation.rst index fb1e89e01..35caa6ea3 100644 --- a/docs/guides/installation.rst +++ b/docs/guides/installation.rst @@ -1,8 +1,7 @@ Installation ============ -Beets requires `Python 3.10 or later`_. You can install it using package -managers, pipx_, pip_ or by using package managers. +Beets requires `Python 3.10 or later`_. You can install it using pipx_ or pip_. .. _python 3.10 or later: https://www.python.org/downloads/ @@ -46,69 +45,36 @@ installation page`_ to get it set up. .. _pipx installation page: https://pipx.pypa.io/stable/installation/ -Using a Package Manager ------------------------ +Managing Plugins with ``pipx`` +------------------------------ -Depending on your operating system, you may be able to install beets using a -package manager. Here are some common options: +When using pipx_, you can install beets with built-in plugin dependencies using +extras, inject third-party packages, and upgrade everything cleanly. -.. attention:: +Install beets with extras for built-in plugins: - Package manager installations may not provide the latest version of beets. +.. code-block:: console - 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. + pipx install "beets[lyrics,lastgenre]" - Additionally, installing external beets plugins may be surprisingly - difficult when using a package manager. +If you already have beets installed, reinstall with a new set of extras: -- 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. +.. code-block:: console -.. _alpine package: https://pkgs.alpinelinux.org/package/edge/community/x86_64/beets + pipx install --force "beets[lyrics,lastgenre]" -.. _arch extra: https://archlinux.org/packages/extra/any/beets/ +Inject additional packages into the beets environment (useful for third-party +plugins): -.. _aur: https://aur.archlinux.org/packages/beets-git/ +.. code-block:: console -.. _debian details: https://tracker.debian.org/pkg/beets + pipx inject beets -.. _dnf package: https://packages.fedoraproject.org/pkgs/beets/ +To upgrade beets and all injected packages: -.. _freebsd: https://www.freshports.org/audio/beets/ +.. code-block:: console -.. _nixos: https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/python-modules/beets - -.. _openbsd: https://openports.pl/path/audio/beets - -.. _ubuntu details: https://launchpad.net/ubuntu/+source/beets - -.. _void package: https://github.com/void-linux/void-packages/tree/master/srcpkgs/beets + pipx upgrade beets Installation FAQ ---------------- @@ -163,3 +129,52 @@ platform as well. .. _notes for arm: https://github.com/beetbox/beets/discussions/4910 .. _older arm reference: https://discourse.beets.io/t/diary-of-beets-on-arm-odroid-hc4-armbian/1993 + +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) + +.. _alpine package: https://pkgs.alpinelinux.org/package/edge/community/x86_64/beets + +.. _arch btw: https://archlinux.org/packages/extra/any/beets/ + +.. _aur: https://aur.archlinux.org/packages/beets-git/ + +.. _debian details: https://tracker.debian.org/pkg/beets + +.. _dnf package: https://packages.fedoraproject.org/pkgs/beets/ + +.. _freebsd: https://www.freshports.org/audio/beets/ + +.. _nixos: https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/python-modules/beets + +.. _openbsd: https://openports.pl/path/audio/beets + +.. _ubuntu details: https://launchpad.net/ubuntu/+source/beets + +.. _void package: https://github.com/void-linux/void-packages/tree/master/srcpkgs/beets