Switch from poetry to uv

.github/workflows/check.yml

@@ -9,12 +9,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - name: Setup Python 3.12
-        uses: actions/setup-python@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
         with:
-          python-version: 3.12
+          enable-cache: true
+      - name: Setup Python 3.12
+        run: uv python install 3.12
       - name: Install dependencies
-        run: make poetry install
+        run: make install
       - name: Format and lint
         run: make lint
       - name: Run tests

.gitignore

@@ -98,6 +98,7 @@ ipython_config.py
 #   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
 #   This is especially recommended for binary packages to ensure reproducibility, and is more
 #   commonly ignored for libraries.
+#   https://docs.astral.sh/uv/guides/projects/#lockfile
 #uv.lock
 
 # poetry

AGENTS.md

@@ -8,7 +8,7 @@ This file provides guidelines for AI coding agents (e.g., GitHub Copilot, Cursor
 
 This is a **Python project template** that provides a pre-configured, production-ready starting point for Python applications. It includes out-of-the-box support for:
 
-- **Packaging & dependency management** via [Poetry](https://python-poetry.org)
+- **Packaging & dependency management** via [uv](https://python-uv.org)
 - **CLI** via [click](https://click.palletsprojects.com)
 - **Testing & coverage** via [pytest](https://pytest.org) and [coverage](https://coverage.readthedocs.io)
 - **Linting, formatting & import sorting** via [ruff](https://docs.astral.sh/ruff)
@@ -41,7 +41,7 @@ This is a **Python project template** that provides a pre-configured, production
 ├── Makefile                    # Workflow automation targets
 ├── mkdocs.yml                  # MkDocs configuration
 ├── pyproject.toml              # Project metadata, dependencies, and tool configuration
-└── poetry.lock                 # Locked dependency versions (do not edit manually)
+└── uv.lock                 # Locked dependency versions (do not edit manually)
 ```
 
 > **Note:** The `project/` folder is the template placeholder. After initialising a real project with `make project NAME=...`, it is renamed to the chosen package name.
@@ -53,14 +53,14 @@ This is a **Python project template** that provides a pre-configured, production
 ### Prerequisites
 
 - Python 3.12+
-- [pipx](https://pipx.pypa.io) (to install Poetry)
+- [pipx](https://pipx.pypa.io) (to install uv)
 - Docker (for Dev Container or containerised runs)
 
 ### First-time setup
 
 ```bash
-# 1. Install Poetry (if not already installed)
-make poetry
+# 1. Install uv (if not already installed)
+make uv
 
 # 2. Install all dependencies
 make install
@@ -88,7 +88,7 @@ make project NAME="my-project" DESCRIPTION="My app" AUTHOR="Your Name" EMAIL="yo
 | Update dependencies | `make update` |
 | Lint and format | `make lint` |
 | Run tests with coverage | `make test` |
-| Run app locally | `app` (after `make venv`) or `poetry run app` |
+| Run app locally | `app` (after `make venv`) or `uv run app` |
 | Run app in Docker | `docker compose run app` |
 | Serve docs locally | `make local` |
 | Deploy docs to GitHub Pages | `make docs` |
@@ -130,7 +130,7 @@ make project NAME="my-project" DESCRIPTION="My app" AUTHOR="Your Name" EMAIL="yo
 
 ## Dependencies
 
-- Always use Poetry for dependency management (`poetry add <package>`)
+- Always use uv for dependency management (`uv add <package>`)
 - Use Pydantic for data models
 - Use Pydantic-settings for environment variable configuration in a `settings.py` file
 
@@ -147,8 +147,8 @@ Use `make` targets for all common workflows: lint, test, run locally, and deploy
 ## Notes
 
 - Python 3.12+ required
-- Dependencies are managed via `pyproject.toml` and locked in `poetry.lock`
-- Do not edit `poetry.lock` directly; use `make update` to update dependencies
+- Dependencies are managed via `pyproject.toml` and locked in `uv.lock`
+- Do not edit `uv.lock` directly; use `make update` to update dependencies
 
 ## Coding Conventions
 

Dockerfile

@@ -1,6 +1,7 @@
 FROM python:3.12-alpine
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 WORKDIR /code
-RUN apk add -u make poetry
+RUN apk add -u make
 COPY . .
 RUN make install
-ENTRYPOINT ["poetry", "run", "app"]
+ENTRYPOINT ["uv", "run", "app"]

Makefile

@@ -22,41 +22,41 @@ project: # Rename project (run once)
 	@sed -i '' 's/^github: \[.*\]/github: \[${GITHUB}\]/' .github/FUNDING.yml
 	@sed -i '' 's/^patreon: .*/patreon: # Put your Patreon username here/' .github/FUNDING.yml
 
-poetry:  # Install Poetry
-	pipx install -f poetry
+uv:  # Install uv
+	pipx install -f uv
 
 venv:
-	poetry env activate
+	uv venv
 
 install: # Install dependencies and project
-	poetry install
+	uv sync
 
 update: # Update dependencies
-	poetry update
+	uv lock --update
 
 precommit: # Install pre-commit hooks
-	poetry run pre-commit autoupdate
-	poetry run pre-commit install
+	uv run pre-commit autoupdate
+	uv run pre-commit install
 
 pre-commit: precommit
 
 lint:
-	poetry run ruff check --fix
-	poetry run ruff format
-	poetry run pyright .
+	uv run ruff check --fix
+	uv run ruff format
+	uv run pyright .
 
 coverage:
-	poetry run coverage run -m pytest .
-	poetry run coverage report -m
-	poetry run coverage xml
+	uv run coverage run -m pytest .
+	uv run coverage report -m
+	uv run coverage xml
 
 test: coverage
 
 .PHONY: docs
 docs: # Build and deploy documentation to GitHub pages
-	poetry run mkdocs gh-deploy --force
+	uv run mkdocs gh-deploy --force
 
 local: # Serve documentation on a local server
-	poetry run mkdocs serve
+	uv run mkdocs serve
 
-all: poetry install precommit lint test venv
+all: uv install precommit lint test venv

docs/CONTRIBUTING.md

@@ -30,7 +30,7 @@ To make contributing as easy and fast as possible, you'll want to run tests and
 You'll need the following prerequisites:
 
 - **Python 3.12+**
-- **Poetry**
+- **uv**
 - **git**
 - **make**
 
@@ -41,7 +41,7 @@ You'll need the following prerequisites:
 - Install the project dependencies:
 
 ```bash
-make poetry install pre-commit
+make uv install pre-commit
 ```
 - Create a new branch (with a descriptive name) for your changes:
 

docs/README.md

@@ -5,7 +5,7 @@
 
 A Python project template that comes out of the box with configuration for:
 
-- Packaging and dependency management using [Poetry](https://python-poetry.org)
+- Packaging and dependency management using [uv](https://python-uv.org)
 - Command Line Interface (CLI) using [click](https://click.palletsprojects.com)
 - Testing using [pytest](https://pytest.org)
 - Code coverage using [coverage](https://coverage.readthedocs.io)
@@ -61,14 +61,14 @@ Parameter | Description
 
 ### Local environment
 - Python 3.12+ (You can update the [`pyproject.toml`](../pyproject.toml#L39) for lower versions)
-- Pipx (*optional* - used to install Poetry if not already installed)
+- Pipx (*optional* - used to install uv if not already installed)
 
 ## Setup
 
-### Install Poetry
-To install poetry, if not installed (requires pipx), run:
+### Install uv
+To install uv, if not installed (requires pipx), run:
 ```bash
-make poetry
+make uv
 ```
 
 ### Install / Update dependencies
@@ -107,10 +107,10 @@ make test
 ```
 
 ## Running the project
-A Poetry script, with the name `app`, is defined in the [pyproject.toml](../pyproject.toml#L36) file, to let you to run the project as a shell command.
+A uv script, with the name `app`, is defined in the [pyproject.toml](../pyproject.toml#L36) file, to let you to run the project as a shell command.
 
 ### Local / Dev container
-> Make sure to activate the virtual environment using `make venv` to be able to run `app` without `poetry run`
+> Make sure to activate the virtual environment using `make venv` to be able to run `app` without `uv run`
 
 Try running `app -h` or `app --help` to get the help message of your app:
 ```bash