Migrate from Poetry to uv for dependency management (PP-4076)

.github/dependabot.yml

@@ -3,11 +3,13 @@
 
 version: 2
 updates:
-  - package-ecosystem: "pip"
+  - package-ecosystem: "uv"
     directory: "/"
     schedule:
       interval: "daily"
     versioning-strategy: increase-if-necessary
+    cooldown:
+      default-days: 4
 
   - package-ecosystem: "github-actions"
     directory: "/"

.github/workflows/build.yml

@@ -48,18 +48,16 @@ jobs:
           fetch-depth: 0
 
       # Creates version files we use to track the version of code in the container
-      - name: Set up Python
-        uses: actions/setup-python@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.0.0
         with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
           python-version: "3.12"
+          activate-environment: true
 
-      - name: Install Poetry
-        uses: ./.github/actions/poetry
-
-      - name: Setup Dunamai
-        run: poetry install --only ci --no-root
-        env:
-          POETRY_VIRTUALENVS_CREATE: false
+      - name: Setup Dunamai (uv ci group)
+        run: uv sync --frozen --only-group ci
 
       - name: Create version file
         run: |
@@ -367,7 +365,7 @@ jobs:
           bash -c "
             cat src/palace/manager/_version.py &&
             source env/bin/activate &&
-            poetry sync --without ci --no-root &&
+            uv sync --frozen --active &&
             pytest --no-cov tests
           "
 

.github/workflows/lint.yml

@@ -13,22 +13,16 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
-      - name: Set up Python
-        uses: actions/setup-python@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.0.0
         with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
           python-version: ${{ env.PYTHON_VERSION }}
-
-      - name: Install Poetry
-        uses: ./.github/actions/poetry
-        with:
-          cache: true
-          cache-restore-only: true
+          activate-environment: true
 
       - name: Install Pre-commit
-        run: |
-          poetry install --only ci --no-root
-        env:
-          POETRY_VIRTUALENVS_CREATE: false
+        run: uv sync --frozen --only-group ci
 
       - name: Restore pre-commit cache
         uses: actions/cache@v5

.github/workflows/mypy.yml

@@ -12,19 +12,16 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
-      - name: Set up Python 🐍
-        uses: actions/setup-python@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.0.0
         with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
           python-version: ${{ env.PYTHON_VERSION }}
-
-      - name: Install Poetry 🎸
-        uses: ./.github/actions/poetry
-        with:
-          cache: true
-          cache-restore-only: true
+          activate-environment: true
 
       - name: Install Python Packages 📦
-        run: poetry install --without ci --no-root
+        run: uv sync --frozen --no-group ci
 
       - name: Run MyPy 🪄
-        run: poetry run mypy
+        run: mypy

.github/workflows/test.yml

@@ -33,16 +33,15 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install Poetry
-        uses: ./.github/actions/poetry
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.0.0
         with:
-          cache: true
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+          activate-environment: true
 
       - name: Install Tox
-        run: |
-          poetry install --only ci --no-root
-        env:
-          POETRY_VIRTUALENVS_CREATE: false
+        run: uv sync --frozen --only-group ci
 
       - name: Run Tests
         run: tox

.gitignore

@@ -89,3 +89,6 @@ celerybeat-schedule.db
 .claude/
 !.claude/settings.json
 CLAUDE.local.md
+
+# direnv
+.envrc

.pre-commit-config.yaml

@@ -14,6 +14,7 @@ repos:
       - id: check-executables-have-shebangs
       - id: check-merge-conflict
       - id: check-added-large-files
+        exclude: ^uv\.lock$
       - id: mixed-line-ending
 
   - repo: https://github.com/asottile/pyupgrade
@@ -41,13 +42,6 @@ repos:
     hooks:
       - id: black
         name: Run black
-        args:
-          - -t
-          - py312
-          - -t
-          - py313
-          - -t
-          - py314
 
   - repo: https://github.com/PyCQA/isort
     rev: 6.0.1

CLAUDE.md

@@ -27,14 +27,14 @@ through mobile and web applications.
 
 **Development & Testing:**
 - pytest, tox
-- Poetry (package management)
+- uv (package management)
 - pre-commit (linting/formatting)
 - mypy (type checking)
 
 ## Code Conventions
 
 - Pre-commit for linting/formatting code
-- Poetry for package management
+- uv for package management
 - `pyproject.toml` for project configuration
 - Doc comments use reStructuredText style
 - Type hint all code with mypy validation

README.md

@@ -71,38 +71,58 @@ Most distributions will offer Python packages. On Arch Linux, the following comm
 pacman -S python
 ```
 
-#### pyenv
+#### uv
 
-[pyenv](https://github.com/pyenv/pyenv) lets you easily switch between multiple versions of Python. It can be
-[installed](https://github.com/pyenv/pyenv-installer) using the command `curl https://pyenv.run | bash`. You can then
-install the version of Python you want to work with.
+This project uses [uv](https://docs.astral.sh/uv/) for Python version management, virtual environment
+management, and dependency management.
 
-It is recommended that [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv) be used to allow `pyenv`
-to manage _virtual environments_ in a manner that can be used by the [poetry](#poetry) tool. The `pyenv-virtualenv`
-plugin can be installed by cloning the relevant repository into the `plugins` subdirectory of your `$PYENV_ROOT`:
+uv can be installed using the command:
 
 ```sh
-mkdir -p $PYENV_ROOT/plugins
-cd $PYENV_ROOT/plugins
-git clone https://github.com/pyenv/pyenv-virtualenv
+curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
-After cloning the repository, `pyenv` now has a new `virtualenv` command:
+More information about installation options can be found in the
+[uv documentation](https://docs.astral.sh/uv/getting-started/installation/).
+
+uv can install and manage Python versions for you. To install the version used by this project:
 
 ```sh
-$ pyenv virtualenv
-pyenv-virtualenv: no virtualenv name given.
+uv python install 3.12
 ```
 
-#### Poetry
+#### direnv (optional, recommended)
 
-You will need to set up a local virtual environment to install packages and run the project. This project uses
-[poetry](https://python-poetry.org/) for dependency management.
+[direnv](https://direnv.net/) automatically activates the project's virtual environment when you `cd`
+into the directory, so you can run commands like `tox`, `pre-commit`, and `mypy` directly without the
+`uv run` prefix.
 
-Poetry can be installed using the command `curl -sSL https://install.python-poetry.org | python3 -`.
+Install direnv:
 
-More information about installation options can be found in the
-[poetry documentation](https://python-poetry.org/docs/master/#installation).
+```sh
+# OSX
+brew install direnv
+
+# Linux (Arch)
+pacman -S direnv
+```
+
+Add the shell hook to your profile (`~/.zshrc` or `~/.bashrc`):
+
+```sh
+eval "$(direnv hook zsh)"   # or: eval "$(direnv hook bash)"
+```
+
+Create a `.envrc` file in the project root:
+
+```sh
+echo 'source .venv/bin/activate' > .envrc
+direnv allow
+```
+
+Now whenever you enter the project directory the `.venv` is activated automatically, and it deactivates
+when you leave. If you use direnv, the `uv run` prefix in the commands below is not needed — you can
+call `python`, `tox`, `pre-commit`, etc. directly.
 
 ### OpenSearch
 
@@ -371,51 +391,26 @@ Optional display settings for the WebReader:
 
 ## Running the Application
 
-As mentioned in the [pyenv](#pyenv) section, the `poetry` tool should be executed within a virtual environment
-to ensure it uses the expected Python version. To use a particular Python version,
-create a local virtual environment in the cloned `circulation` repository directory. For example, to use Python 3.12.1:
-
-```sh
-pyenv virtualenv 3.12.1 circ
-```
-
-This will create a new local virtual environment called `circ` that uses Python 3.12.1. Switch to that environment:
-
-```sh
-pyenv local circ
-```
-
-On most systems, using `pyenv` will adjust your shell prompt to indicate which virtual environment you
-are now in. For example, the version of Python installed in your operating system might be `3.11.0`, but
-using a virtual environment can substitute, for example, `3.12.1`:
-
-```sh
-$ python --version
-Python 3.11.0
-
-$ pyenv local circ
-(circ) $ python --version
-Python 3.12.1
-```
-
-For brevity, these instructions assume that all shell commands will be executed within a virtual environment.
+uv manages the project's virtual environment for you. The first time you run `uv sync` (or any
+`uv run` command) uv will create a `.venv/` directory in the project root using the Python version
+specified in `pyproject.toml`, and install the project's dependencies into it.
 
-Install the dependencies (including dev and CI):
+Install all dependencies (including both `dev` and `ci` groups):
 
 ```sh
-poetry install
+uv sync --all-groups
 ```
 
-Install only the production dependencies:
+Install only the production dependencies (no dev group):
 
 ```sh
-poetry install --only main,pg
+uv sync --no-dev
 ```
 
 Run the application with:
 
 ```sh
-poetry run python app.py
+uv run python app.py
 ```
 
 Check that there is now a web server listening on port `6500`:
@@ -427,7 +422,7 @@ curl http://localhost:6500/
 You can start a celery worker with:
 
 ```sh
-poetry run celery -A "palace.manager.celery.app" worker --concurrency 1 --pool solo --beat
+uv run celery -A "palace.manager.celery.app" worker --concurrency 1 --pool solo --beat
 ```
 
 ### The Admin Interface
@@ -674,7 +669,7 @@ testing the branch, or deploying hotfixes.
 To install the tools used by CI run:
 
 ```sh
-poetry install --only ci
+uv sync --only-group ci
 ```
 
 ## Testing
@@ -712,8 +707,8 @@ You need to have the Python versions you are testing against installed on your l
 for installed Python versions, but does not install new Python versions. If `tox` doesn't find the Python version its
 looking for it will give an `InterpreterNotFound` errror.
 
-[Pyenv](#pyenv) is a useful tool to install multiple Python versions, if you need to install
-missing Python versions in your system for local testing.
+If you need to install missing Python versions, you can use `uv python install <version>` or
+[pyenv](https://github.com/pyenv/pyenv) to manage multiple Python installations.
 
 #### Docker
 

docker/Dockerfile

@@ -17,15 +17,16 @@
 COPY --chmod=644 docker/services/logrotate /etc/
 RUN mv /etc/cron.daily/logrotate /etc/cron.hourly/logrotate
 
-# Copy our poetry files into the image and install our dependencies.
-COPY --chown=palace:palace poetry.lock pyproject.toml /var/www/circulation/
-RUN . env/bin/activate && \
-    poetry sync --only main,pg --no-root
+# Copy our uv files into the image and install our dependencies.
+COPY --chown=palace:palace uv.lock pyproject.toml /var/www/circulation/
+RUN uv sync --frozen --no-dev --no-install-project
 
 COPY --chown=palace:palace . /var/www/circulation
 
-RUN . env/bin/activate && \
-    poetry install --only-root
+# Install the project itself as a non-editable install. Omitting
+# --no-install-project (and passing --no-editable) is the recommended
+# pattern for production Docker builds with uv.
+RUN uv sync --frozen --no-dev --no-editable
 
 ###############################################################################
 ## Circ-exec Image