Python Template

A minimal boilerplate for starting new Python projects with a consistent development setup.

Included by default:

• Python 3.14+
• uv for dependency and environment management
• ruff for linting and formatting
• mypy for static type checking
• pytest for testing
• pre-commit for automated checks
• GitHub Actions CI
• .env support
• src/ project layout

Requirements

Make sure the following are installed:

• Python 3.14+
• uv

Getting Started

Create a new repository from this template, then clone it locally.

Install the project dependencies:

uv sync

Install the pre-commit hooks:

uv run pre-commit install

Create your local environment file:

cp .env.example .env

The .env file is ignored by Git and should be used for local secrets and configuration.

Configure the Project

Before starting development, update the project-specific values in pyproject.toml.

Project metadata

Update:

[project]
name = "project-name"
version = "0.1.0"
description = "Short project description"

Package name

The default package lives under:

src/project_name/

Rename project_name to match your project.

Remember to update any references to project_name in:

• pyproject.toml
• tests/
• CI or tooling configuration, if applicable

Application command

The template exposes an application command through:

[project.scripts]
app = "project_name.main:main"

After renaming the package, update it accordingly:

[project.scripts]
app = "awesome_app.main:main"

This maps:

uv run app

to the main() function inside:

src/awesome_app/main.py

Running the Application

The recommended way to run the project is:

uv run app

You can also run the module directly:

uv run python -m project_name.main

Replace project_name with your actual package name.

Development

Run tests

uv run pytest

Lint

uv run ruff check .

Automatically fix supported lint issues:

uv run ruff check . --fix

Format

uv run ruff format .

Type check

uv run mypy src tests

Run all pre-commit checks

uv run pre-commit run --all-files

Pre-commit hooks also run automatically when committing after:

uv run pre-commit install

Adding Dependencies

Add a runtime dependency:

uv add <package>

Add a development dependency:

uv add --dev <package>

uv automatically updates both pyproject.toml and uv.lock.

Environment Variables

Put local environment variables in:

.env

License

This template uses the MIT License.

Update the copyright information in LICENSE before publishing a new project.