Python Repository Template

The ultimate 2025 Python repository template. Simple, fast, customizable, and ready to use.

---

I wrote a blog post about this template! Check it out here

🎯 Core Features

Development Tools

• 📦 UV - Ultra-fast Python package manager
• 🚀 Just - Modern command runner with powerful features
• 💅 Ruff - Lightning-fast linter and formatter
• 🔍 Mypy - Static type checker
• 🧪 Pytest - Testing framework with fixtures and plugins
• 🧾 Loguru - Python logging made simple

Infrastructure

• 🛫 Pre-commit hooks
• 🐳 Docker support with multi-stage builds and distroless images
• 🔄 GitHub Actions CI/CD pipeline

Usage

The template is based on UV as package manager and Just as command runner. You need to have both installed in your system to use this template.

Once you have those, you can just run

just dev-sync

to create a virtual environment and install all the dependencies, including the development ones. If instead you want to build a "production-like" environment, you can run

just prod-sync

In both cases, all extra dependencies will be installed (notice that the current pyproject.toml file has no extra dependencies).

You also need to install the pre-commit hooks with:

just install-hooks

Formatting, Linting and Testing

You can configure Ruff by editing the .ruff.toml file. It is currently set to the default configuration.

Format your code:

just format

Run linters (ruff and mypy):

just lint

Run tests:

just test

Do all of the above:

just validate

Executing

The code is a simple hello world example, which just requires a number as input. It will output the sum of the provided number with a random number. You can run the code with:

just run 5

Docker

The template includes a multi stage Dockerfile, which produces an image with the code and the dependencies installed. You can build the image with:

just dockerize

Github Actions

The template includes two Github Actions workflows.

The first one runs tests and linters on every push on the main and dev branches. You can find the workflow file in .github/workflows/main-list-test.yml.

The second one is triggered on every tag push and can also be triggered manually. It builds the distribution and uploads it to PyPI. You can find the workflow file in .github/workflows/publish.yaml.