How I start a Python project

Intro

This template captures a minimal, modern setup for Python projects: dependency & environment management with uv, linting and formatting with ruff, documentation with MkDocs + mkdocstrings, and versioning via Git tags (optionally automated with bump-my-version). Copy commands as-is and adapt names to your project.

Package Manager: uv

uv manages virtual environments and dependencies. There are many choices from plain old pip to more complex tools like Poetry. However I prefer uv for its simplicity and speed. And it can also manage Python installations.

Initialize a new project

mkdir my-python-project && cd my-python-project
uv init --app .
uv venv --python 3.14

Add Dependencies

uv add requests numpy pandas         # runtime dependencies
uv add --dev ruff mkdocs-material
uv sync

Lint & Format

I use ruff for both linting and formatting to keep things simple.

# pyproject.toml (ruff)
[tool.ruff]
line-length = 120
target-version = "py312"

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]
ignore = []

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false

uv run ruff check --fix .
uv run ruff format .

Create Docs

mkdocs with mkdocs-material are my favorite tools for creating project documentation. One of the best plugins is mkdocstrings which can automatically generate API reference docs from your code, type hints and docstrings.

uv add --dev mkdocs-material mkdocstrings
uv run mkdocs new .
# creates mkdocs.yml and docs/index.md

Enable mkdocstrings (Python)

site_name: My Python Project
theme:
  name: material
plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          options:
            show_source: true

Reference your code in docs/index.md

# API Reference

::: my_package.module

Serve or build

uv run mkdocs serve   # local preview
uv run mkdocs build   # outputs to site/

Versioning {#versioning}

Keep a single source of truth in pyproject.toml and tag releases in Git. Optional automation via bump-my-version.

pyproject.toml (project metadata)

[project]
name = "my-python-project"
version = "0.1.0"
description = "Awesome project"
requires-python = ">=3.12"
authors = [{ name = "Giray Coskun" }]
readme = "README.md"

Version Bump

# usage
uv version --bump minor   # 0.1.0 -> 0.2.0 (major, minor, patch, pre)
git add . && git commit -m "chore: release v0.2.0"
git push && git push --tags