A Python project template built with uv. It already includes:
- Ruff for linting and formatting;
- mypy for type checking;
- pytest for testing;
- coverage for test coverage reporting;
- Poe the Poet for task management;
- Renovate configuration for automated dependency updates;
- semantic-release configuration with conventional commits for automated releases to PyPI.
The template starts with a minimal package named uv_python_project_template, which will be renamed when you create a new repository from this template.
<root directory>
├── src/ # source root for the Python package
│ └── uv_python_project_template/ # main package (renamed into your project name)
│ ├── __init__.py
│ └── main.py # application entry point
├── test/ # test package
│ └── test_my_class.py # pytest example
├── .github/ # configuration of GitHub Actions
│ └── workflows/
│ ├── check.yml # runs checks and tests on multiple OSs and Python versions
│ ├── deploy.yml # releases to PyPI/TestPyPI with semantic-release
│ └── init.yml # initializes repositories created from this template
├── CHANGELOG.md # generated release changelog
├── LICENSE # license file
├── package.json # Node.js dependencies for semantic-release
├── pyproject.toml # Python project configuration, dependencies, and tasks
├── renovate.json # configuration of Renovate bot for dependency updates
├── release.config.mjs # semantic-release configuration
├── rename-template.sh # CI helper script used by init.yml to rename the project
└── uv.lock # locked Python dependency versions- Only uv and
- Node.js and npm, for semantic-release and package publishing.
You can install uv following the instructions in the documentation.
You can install and handle Python versions with uv:
uv python install 3.12
uv python pin 3.12
uv python list-
Create a new repository from this template on GitHub.
-
Let the initialization workflow run.
The
.github/workflows/init.ymlworkflow runs automatically onmainormasterwhen the repository is not marked as a template. It callsrename-template.shto replace the template placeholders with the repository name, removes the initialization workflow, and commits the result. -
Install dependencies:
uv sync
-
Run the checks:
uv run poe static-checks uv run poe format-check uv run poe test -
Start building your project in
src/uv_python_project_template/and add tests undertest/.
uv run uv_python_project_template to run the application entry point defined in pyproject.toml.
| Command | Description |
|---|---|
uv sync |
Create or update the local environment from pyproject.toml and uv.lock. |
uv run uv_python_project_template |
Run the application entry point. |
uv add <package> |
Add a runtime dependency. |
uv add --dev <package> |
Add a development dependency. |
uv remove <package> |
Remove a dependency. |
uv lock |
Update the lock file after dependency changes. |
uv sync --locked |
Sync the environment strictly to the locked versions. |
Project task aliases are defined in pyproject.toml under [tool.poe.tasks] and
can be run through uv.
| Command | Description |
|---|---|
uv run poe test |
Run the pytest test suite. |
uv run poe coverage |
Run tests through coverage. |
uv run poe coverage-report |
Print a terminal coverage report with missing lines. |
uv run poe coverage-html |
Generate an HTML coverage report in htmlcov/. |
uv run poe ruff-check |
Run Ruff lint checks. |
uv run poe ruff-fix |
Run Ruff and apply automatic fixes. |
uv run poe format |
Format code with Ruff. |
uv run poe format-check |
Check formatting without changing files. |
uv run poe mypy |
Type-check src/ and test/ with Mypy. |
uv run poe compile |
Compile src/ and test/ to catch syntax errors. |
uv run poe static-checks |
Run the configured static checks, currently Ruff and Mypy. |
New versions are automatically released on PyPi via GitHub Actions, when a push is made on the main or master branch.
The version number is updated automatically by the semantic-release tool, which uses the commit messages to infer the type of the release (major, minor, patch).
It is paramount that the commit messages follow the Conventional Commits specification,
in order for semantic-release to compute version numbers correctly.
For successfully publishing, configure these repository secrets as needed:
PYPI_TOKEN: token for publishing to PyPI.TEST_PYPI_TOKEN: token for publishing to TestPyPI.RELEASE_TOKEN: GitHub token used by semantic-release.
The workflow dry-runs releases outside main or master, and also dry-runs the
initial commit.
The project is configured to use Renovate to automatically open pull-requests
to update dependencies declared in pyproject.toml.
By default, Renovate will assign such pull-requests to the user who created the repository from this template.
If the project has tests (which is the case for this template), Renovate will only merge such pull-requests if all tests pass.
When some test fails, Renovate will leave a comment on the pull-request, so that you can fix the issue manually.
To make Renovate work, you need to enable it for your repository. To do so, please follow the instruction at https://docs.renovatebot.com/getting-started/installing-onboarding/#hosted-githubcom-app
Finally, please remember to enable PR auto-merging in your repository settings, otherwise Renovate will not be able to merge the pull-requests it opens, even if all tests pass. To do so, please follow the instructions available here.
Notice that the combination between Renovate, and Semantic Release may lead to a number of releases being created automatically.
This template is distributed under the license included in LICENSE.