Switch to uv

.github/workflows/ci.yaml

@@ -28,12 +28,10 @@ jobs:
       - uses: actions/checkout@v5
       - name: Install Python tools
         uses: BrandonLWhite/pipx-install-action@v1.0.3
-      - name: Setup Python with poetry caching
-        # poetry cache requires poetry to already be installed, weirdly
-        uses: actions/setup-python@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
         with:
           python-version: ${{ matrix.python-version }}
-          cache: poetry
 
       - name: Install system dependencies on Windows
         if: matrix.platform == 'windows-latest'
@@ -72,15 +70,15 @@ jobs:
       - if: ${{ env.IS_MAIN_PYTHON != 'true' }}
         name: Test without coverage
         run: |
-          poetry install --without=lint --extras=autobpm --extras=discogs --extras=lyrics --extras=replaygain --extras=reflink --extras=fetchart --extras=chroma --extras=sonosupdate
+          uv sync --group test --extra autobpm --extra discogs --extra lyrics --extra replaygain --extra reflink --extra fetchart --extra chroma --extra sonosupdate
           poe test
 
       - if: ${{ env.IS_MAIN_PYTHON == 'true' }}
         name: Test with coverage
         env:
           LYRICS_UPDATED: ${{ steps.lyrics-update.outputs.any_changed }}
         run: |
-          poetry install --extras=autobpm --extras=discogs --extras=lyrics --extras=docs --extras=replaygain --extras=reflink --extras=fetchart --extras=chroma --extras=sonosupdate
+          uv sync --group test --extra autobpm --extra discogs --extra lyrics --extra docs --extra replaygain --extra reflink --extra fetchart --extra chroma --extra sonosupdate
           poe docs
           poe test-with-coverage
 

.github/workflows/integration_test.yaml

@@ -14,13 +14,13 @@ jobs:
       - uses: actions/checkout@v5
       - name: Install Python tools
         uses: BrandonLWhite/pipx-install-action@v1.0.3
-      - uses: actions/setup-python@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: poetry
 
       - name: Install dependencies
-        run: poetry install
+        run: uv sync
 
       - name: Test
         env:

.github/workflows/lint.yaml

@@ -37,15 +37,15 @@ jobs:
         with:
           files: |
             **.py
-            poetry.lock
+            uv.lock
 
       - name: Check changed python files
         id: changed-python-files
         env:
           CHANGED_PYTHON_FILES: ${{ steps.raw-changed-python-files.outputs.all_changed_files }}
         run: |
-          if [[ " $CHANGED_PYTHON_FILES " == *" poetry.lock "* ]]; then
-            # if poetry.lock is changed, we need to check everything
+          if [[ " $CHANGED_PYTHON_FILES " == *" uv.lock "* ]]; then
+            # if uv.lock is changed, we need to check everything
             CHANGED_PYTHON_FILES="."
           fi
           echo "all_changed_files=$CHANGED_PYTHON_FILES" >> "$GITHUB_OUTPUT"
@@ -59,13 +59,13 @@ jobs:
       - uses: actions/checkout@v5
       - name: Install Python tools
         uses: BrandonLWhite/pipx-install-action@v1.0.3
-      - uses: actions/setup-python@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: poetry
 
       - name: Install dependencies
-        run: poetry install --only=lint
+        run: uv sync --only-group lint
 
       - name: Check code formatting
         # the job output will contain colored diffs with what needs adjusting
@@ -80,13 +80,13 @@ jobs:
       - uses: actions/checkout@v5
       - name: Install Python tools
         uses: BrandonLWhite/pipx-install-action@v1.0.3
-      - uses: actions/setup-python@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: poetry
 
       - name: Install dependencies
-        run: poetry install --only=lint
+        run: uv sync --only-group lint
 
       - name: Lint code
         run: poe lint --output-format=github ${{ needs.changed-files.outputs.changed_python_files }}
@@ -100,13 +100,13 @@ jobs:
       - uses: actions/checkout@v5
       - name: Install Python tools
         uses: BrandonLWhite/pipx-install-action@v1.0.3
-      - uses: actions/setup-python@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: poetry
 
       - name: Install dependencies
-        run: poetry install --only=typing
+        run: uv sync --only-group typing
 
       - name: Type check code
         uses: liskin/gh-problem-matcher-wrap@v3
@@ -125,13 +125,13 @@ jobs:
           fetch-depth: 0 # needed to get the full git history for the changelog check
       - name: Install Python tools
         uses: BrandonLWhite/pipx-install-action@v1.0.3
-      - uses: actions/setup-python@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: poetry
 
       - name: Install dependencies
-        run: poetry install --extras=docs
+        run: uv sync --extra docs --group lint
 
       - name: Add Sphinx problem matchers
         run: |

.github/workflows/make_release.yaml

@@ -20,13 +20,13 @@ jobs:
       - uses: actions/checkout@v5
       - name: Install Python tools
         uses: BrandonLWhite/pipx-install-action@v1.0.3
-      - uses: actions/setup-python@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: poetry
 
       - name: Install dependencies
-        run: poetry install --with=release --extras=docs
+        run: uv sync --no-group test --no-group lint --no-group typing --extra docs
 
       - name: Bump project version
         run: poe bump "${{ env.NEW_VERSION }}"
@@ -51,13 +51,13 @@ jobs:
 
       - name: Install Python tools
         uses: BrandonLWhite/pipx-install-action@v1.0.3
-      - uses: actions/setup-python@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: poetry
 
       - name: Install dependencies
-        run: poetry install --with=release --extras=docs
+        run: uv sync --no-group test --no-group lint --no-group typing --extra docs
 
       - name: Install pandoc
         run: sudo apt update && sudo apt install pandoc -y

CONTRIBUTING.rst

@@ -65,71 +65,66 @@ Development Tools
 
 In order to develop beets, you will need a few tools installed:
 
-- poetry_ for packaging, virtual environment and dependency management
+- uv_ for packaging, virtual environment and dependency management
 - poethepoet_ to run tasks, such as linting, formatting, testing
 
-Python community recommends using pipx_ to install stand-alone command-line
-applications such as above. pipx_ installs each application in an isolated
-virtual environment, where its dependencies will not interfere with your system
-and other CLI tools.
+Follow the `uv installation instructions
+<https://docs.astral.sh/uv/getting-started/installation/>`__ to install uv_.
 
-If you do not have pipx_ installed in your system, follow `pipx installation
-instructions <https://pipx.pypa.io/stable/how-to/install-pipx/>`__ or
+poethepoet_ is a stand-alone CLI tool. The Python community recommends using
+pipx_ to install such tools in isolated environments so their dependencies don't
+interfere with your system. If you don't have pipx_ installed, follow the `pipx
+installation instructions <https://pipx.pypa.io/stable/how-to/install-pipx/>`__
+or run:
 
 .. code-block:: sh
 
     $ python3 -m pip install --user pipx
 
-Install poetry_ and poethepoet_ using pipx_:
+Then install poethepoet_:
 
 ::
 
-    $ pipx install poetry poethepoet
+    $ pipx install poethepoet
 
 .. admonition:: Check ``tool.pipx-install`` section in ``pyproject.toml`` to see supported versions
 
     .. code-block:: toml
 
         [tool.pipx-install]
         poethepoet = ">=0.26"
-        poetry = "<2"
 
 .. _getting-the-source:
 
 Getting the Source
 ++++++++++++++++++
 
 The easiest way to get started with the latest beets source is to clone the
-repository and install ``beets`` in a local virtual environment using poetry_.
-This can be done with:
+repository and install ``beets`` in a local virtual environment using uv_. This
+can be done with:
 
 .. code-block:: bash
 
     $ git clone https://github.com/beetbox/beets.git
     $ cd beets
-    $ poetry install
+    $ uv sync
 
-This will install ``beets`` and all development dependencies into its own
-virtual environment in your ``$POETRY_CACHE_DIR``. See ``poetry install --help``
-for installation options, including installing ``extra`` dependencies for
-plugins.
+This will install ``beets`` and all development dependencies into a ``.venv``
+virtual environment. See ``uv sync --help`` for options, including installing
+``extra`` dependencies for plugins (e.g. ``uv sync --extra fetchart``).
 
-In order to run something within this virtual environment, start the command
-with ``poetry run`` to them, for example ``poetry run pytest``.
-
-On the other hand, it may get tedious to type ``poetry run`` before every
-command. Instead, you can activate the virtual environment in your shell with:
+To run commands within this virtual environment, either activate it:
 
 ::
 
-    $ poetry shell
+    $ source .venv/bin/activate
+    $ pytest
 
-You should see ``(beets-py3.10)`` prefix in your shell prompt. Now you can run
-commands directly, for example:
+Or prefix commands with ``uv run``:
 
 ::
 
-    $ (beets-py3.10) pytest
+    $ uv run pytest
 
 Additionally, poethepoet_ task runner assists us with the most common
 operations. Formatting, linting, testing are defined as ``poe`` tasks in
@@ -351,7 +346,7 @@ Test Dependencies
 The tests have a few more dependencies than beets itself. (The additional
 dependencies consist of testing utilities and dependencies of non-default
 plugins exercised by the test suite.) The dependencies are listed under the
-``tool.poetry.group.test.dependencies`` section in pyproject.toml_.
+``test`` group in the ``dependency-groups`` section of pyproject.toml_.
 
 Writing Tests
 ~~~~~~~~~~~~~
@@ -412,8 +407,6 @@ beets also defines custom pytest markers in ``test/conftest.py``:
 
 .. _poethepoet: https://poethepoet.natn.io/index.html
 
-.. _poetry: https://python-poetry.org/docs/
-
 .. _pyproject.toml: https://github.com/beetbox/beets/blob/master/pyproject.toml
 
 .. _pytest: https://docs.pytest.org/en/stable/
@@ -428,4 +421,6 @@ beets also defines custom pytest markers in ``test/conftest.py``:
 
 .. _unittest: https://docs.python.org/3/library/unittest.html
 
+.. _uv: https://docs.astral.sh/uv/
+
 .. _vim: https://www.vim.org/

docs/changelog.rst

@@ -58,9 +58,14 @@ For plugin developers
   ``TypedDict`` models for releases, recordings, works, and relations. Update
   direct access to raw MusicBrainz response keys if needed.
 
-..
-    Other changes
-    ~~~~~~~~~~~~~
+Other changes
+~~~~~~~~~~~~~
+
+- :doc:`contributing`: The project now uses ``uv`` for packaging, virtual
+  environment, and dependency management, replacing ``poetry``. The build
+  backend has changed from ``poetry-core`` to ``hatchling``. Please see updates
+  in :ref:`development-tools` and :ref:`getting-the-source` for more
+  information. :bug:`5783`
 
 2.9.0 (April 11, 2026)
 ----------------------

docs/dev/plugins/index.rst

@@ -79,14 +79,12 @@ and you're good to go!
     information, see for example pep-3119_.
 
 .. [3] There are a variety of packaging tools available for python, for example
-    you can use poetry_, setuptools_ or hatchling_.
+    you can use setuptools_ or hatchling_.
 
 .. _hatchling: https://hatch.pypa.io/latest/config/build/#build-system
 
 .. _pep-3119: https://peps.python.org/pep-3119/#rationale
 
-.. _poetry: https://python-poetry.org/docs/pyproject/#packages
-
 .. _setuptools: https://setuptools.pypa.io/en/latest/userguide/package_discovery.html#finding-simple-packages
 
 .. _this article: https://realpython.com/python-namespace-package/#setting-up-some-namespace-packages

docs/faq.rst

@@ -152,7 +152,8 @@ helpful to run on the "bleeding edge". To run the latest source:
      .. code-block:: shell
 
          git clone https://github.com/beetbox/beets.git
-         poetry install
+         cd beets
+         pip install -e .
 
      This approach lets you decide where the source is stored, with any changes
      immediately reflected in your environment.

extra/release.py

@@ -208,7 +208,7 @@ def validate_new_version(
 ) -> Version:
     """Validate the version is newer than the current one."""
     with PYPROJECT.open("rb") as f:
-        current = parse(tomli.load(f)["tool"]["poetry"]["version"])
+        current = parse(tomli.load(f)["project"]["version"])
 
     if not value > current:
         msg = f"version must be newer than {current}"