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
- 📦 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
- 🛫 Pre-commit hooks
- 🐳 Docker support with multi-stage builds and distroless images
- 🔄 GitHub Actions CI/CD pipeline
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-syncto 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-syncIn 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-hooksYou can configure Ruff by editing the .ruff.toml file. It is currently set to the default configuration.
Format your code:
just formatRun linters (ruff and mypy):
just lintRun tests:
just testDo all of the above:
just validateThe 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 5The template includes a multi stage Dockerfile, which produces an image with the code and the dependencies installed. You can build the image with:
just dockerizeThe template includes a Github Actions workflow that runs tests and linters on every push on the main branch. You can find the workflow file in .github/workflows/main-list-test.yml.