Skip to content

[docs] remove old contact info (#5462) #5807

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

[docs] remove old contact info (#5462) #5807

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
00a9978
Removed outdated installation instructions.
semohr May 27, 2025
a1cd553
Removed mailing list ref in index.rst
semohr May 27, 2025
4f36617
Added changelog entry.
semohr May 27, 2025
c51e480
Removed duplicate yet.
semohr May 27, 2025
4d68b36
Added pipx refernces
semohr May 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/changelog.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ Bug fixes:
* Fix ``HiddenFileTest`` by using ``bytestring_path()``.
* tests: Fix tests failing without ``langdetect`` (by making it required).
:bug:`5797`
* removed old contact info in docs
:bug:`5462`

For packagers:

Expand Down
3 changes: 1 addition & 2 deletions docs/faq.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ Here are some answers to frequently-asked questions from IRC and elsewhere.
Got a question that isn't answered here? Try the `discussion board`_, or
:ref:`filing an issue <bugs>` in the bug tracker.

.. _mailing list: https://groups.google.com/group/beets-users
.. _discussion board: https://github.com/beetbox/beets/discussions/

.. contents::
Expand Down Expand Up @@ -182,7 +181,7 @@ Please follow these guidelines when reporting an issue:
readable if you put them in a pastebin (e.g.,
`Gist <https://gist.github.com/>`__ or
`Hastebin <https://hastebin.com/>`__), especially when communicating
over IRC or email.
over IRC.
- Turn on beets' debug output (using the -v option: for example,
``beet -v import ...``) and include that with your bug report. Look
through this verbose output for any red flags that might point to the
Expand Down
91 changes: 40 additions & 51 deletions docs/guides/main.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,40 @@ collection better.
Installing
----------

You will need Python.
Beets works on Python 3.8 or later.
Beets requires Python 3.9 or later, you will need to install that first. Depending
on your operating system, you may also be able to install beets from a package
manager, or you can install it with `pipx`_ or `pip`_.

* **macOS** 11 (Big Sur) includes Python 3.8 out of the box.
You can opt for a more recent Python installing it via `Homebrew`_
(``brew install python3``).
There's also a `MacPorts`_ port. Run ``port install beets`` or
``port install beets-full`` to include many third-party plugins.
Using pip
^^^^^^^^^

To use the most recent version of beets, we recommend installing it with
`pipx`_, the Python package manager. If you don't have `pipx`_ installed, you can
follow the instructions on the `pipx installation page`_ to get it set up.

.. code-block:: console

pipx install beets

If you prefer to use `pip`_, you can install beets with the following command:

.. code-block:: console

pip install beets
# or, to install for the current user only:
pip install --user beets


.. attention:: Python 3.13 not officially supported yet!
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you reckon this is needed?

I'm just mindful that we will need to remember to remove it once we support 3.13, and I have no clue how to make sure this happens 🤣

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can't be sure which python versions are installed on a user device. By default the python download page now suggests you install 3.13. So having a note here is kinda necessary to prevent issues for new users.

I guess this note is predominant enough to not miss is in the update ;). We will see.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't we instead just update our supported python version in pyproject.toml?

Currently it supports 3.13 apparently

[tool.poetry.dependencies]
python = ">=3.9,<4"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes that would be preferable but there are some issue with dependencies:

#5575
#5798

Maybe there are even more issues, I only quickly skimmed the open issues.

Copy link
Member

@snejus snejus Jun 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apologies, I wasn't clear. I meant we should update the python version requirement

[tool.poetry.dependencies]
python = ">=3.9,<3.13"

this would ensure that beets is not installable on 3.13.1 afaik.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As part of my testing on Arch it was running 3.13 and it seemed to pull in the packages mentioned in #5798.

I'll need to check again after work

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm happy to remove the 3.13 note from the docs if you'd prefer 🤷

That said, put yourself in the shoes of a new user: just installed Python to try out beets, only to find out 3.13 isn’t supported and there’s no mention of it in the docs. That would be a bit frustrating, having to reinstall python.


If you are using Python 3.13, please be aware that it is not officially supported yet.
You may encounter issues, and we recommend using Python 3.12 or earlier until support is confirmed.


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:

* On **Debian or Ubuntu**, depending on the version, beets is available as an
official package (`Debian details`_, `Ubuntu details`_), so try typing:
Expand All @@ -39,66 +65,31 @@ Beets works on Python 3.8 or later.

* On **FreeBSD**, there's a `beets port <FreeBSD_>`_ at ``audio/beets``.

* On **OpenBSD**, there's a `beets port <OpenBSD_>`_ can be installed with ``pkg_add beets``.

* For **Slackware**, there's a `SlackBuild`_ available.

* 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 <NixOS_>`_ you can install with ``nix-env -i beets``.

.. _DNF package: https://packages.fedoraproject.org/pkgs/beets/
.. _SlackBuild: https://slackbuilds.org/repository/14.2/multimedia/beets/
.. _FreeBSD: http://portsmon.freebsd.org/portoverview.py?category=audio&portname=beets
.. _AUR: https://aur.archlinux.org/packages/beets-git/
.. _Debian details: https://tracker.debian.org/pkg/beets
.. _Ubuntu details: https://launchpad.net/ubuntu/+source/beets
.. _OpenBSD: http://openports.se/audio/beets
.. _Arch extra: https://archlinux.org/packages/extra/any/beets/
.. _Alpine package: https://pkgs.alpinelinux.org/package/edge/community/x86_64/beets
.. _NixOS: https://github.com/NixOS/nixpkgs/tree/master/pkgs/tools/audio/beets
.. _MacPorts: https://www.macports.org

If you have `pip`_, just say ``pip install beets`` (or ``pip install --user
beets`` if you run into permissions problems).

To install without pip, download beets from `its PyPI page`_ and run ``python
setup.py install`` in the directory therein.

.. _its PyPI page: https://pypi.org/project/beets/#files
.. _pip: https://pip.pypa.io

The best way to upgrade beets to a new version is by running ``pip install -U
beets``. You may want to follow `@b33ts`_ on Twitter to hear about progress on
new versions.

.. _@b33ts: https://twitter.com/b33ts

Installing by Hand on macOS 10.11 and Higher
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Starting with version 10.11 (El Capitan), macOS has a new security feature
called `System Integrity Protection`_ (SIP) that prevents you from modifying
some parts of the system. This means that some ``pip`` commands may fail with a
permissions error. (You probably *won't* run into this if you've installed
Python yourself with `Homebrew`_ or otherwise. You can also try `MacPorts`_.)

If this happens, you can install beets for the current user only by typing
``pip install --user beets``. If you do that, you might want to add
``~/Library/Python/3.6/bin`` to your ``$PATH``.

.. _System Integrity Protection: https://support.apple.com/en-us/HT204899
.. _Homebrew: https://brew.sh
.. _pip: https://pip.pypa.io/en/
.. _pipx: https://pipx.pypa.io/stable
.. _pipx installation page: https://pipx.pypa.io/stable/installation/

Installing on Windows
^^^^^^^^^^^^^^^^^^^^^

Installing beets on Windows can be tricky. Following these steps might help you
get it right:

1. If you don't have it, `install Python`_ (you want at least Python 3.8). The
1. If you don't have it, `install Python`_ (you want at least Python 3.9). The
installer should give you the option to "add Python to PATH." Check this
box. If you do that, you can skip the next step.

Expand All @@ -109,7 +100,7 @@ get it right:
should open the "System Properties" screen, then select the "Advanced" tab,
then hit the "Environmental Variables..." button, and then look for the PATH
variable in the table. Add the following to the end of the variable's value:
``;C:\Python38;C:\Python38\Scripts``. You may need to adjust these paths to
``;C:\Python39;C:\Python39\Scripts``. You may need to adjust these paths to
point to your Python installation.

3. Now install beets by running: ``pip install beets``
Expand All @@ -123,9 +114,8 @@ 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".

Because I don't use Windows myself, I may have missed something. If you have
trouble or you have more detail to contribute here, please direct it to
`the mailing list`_.
If you have trouble or you have more detail to contribute here, please direct it to
`the discussion board`_.

.. _install Python: https://python.org/download/
.. _beets.reg: https://github.com/beetbox/beets/blob/master/extra/beets.reg
Expand Down Expand Up @@ -326,6 +316,5 @@ beets blog <https://beets.io/blog/walkthrough.html>`_.
Please let us know what you think of beets via `the discussion board`_ or
`Mastodon`_.

.. _the mailing list: https://groups.google.com/group/beets-users
.. _the discussion board: https://github.com/beetbox/beets/discussions
.. _mastodon: https://fosstodon.org/@beets
1 change: 0 additions & 1 deletion docs/guides/tagger.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -309,5 +309,4 @@ I Hope That Makes Sense
If we haven't made the process clear, please post on `the discussion
board`_ and we'll try to improve this guide.

.. _the mailing list: https://groups.google.com/group/beets-users
.. _the discussion board: https://github.com/beetbox/beets/discussions/
6 changes: 2 additions & 4 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,10 @@ Then you can get a more detailed look at beets' features in the
be interested in exploring the :doc:`plugins </plugins/index>`.

If you still need help, you can drop by the ``#beets`` IRC channel on
Libera.Chat, drop by `the discussion board`_, send email to
`the mailing list`_, or `file a bug`_ in the issue tracker. Please let us know
where you think this documentation can be improved.
Libera.Chat, drop by `the discussion board`_ or `file a bug`_ in the issue tracker.
Please let us know where you think this documentation can be improved.

.. _beets: https://beets.io/
.. _the mailing list: https://groups.google.com/group/beets-users
.. _file a bug: https://github.com/beetbox/beets/issues
.. _the discussion board: https://github.com/beetbox/beets/discussions/

Expand Down