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 fast. Recommended on macOS:

Install uv

curl -Ls https://astral.sh/uv/install.sh | sh
# or via Homebrew
brew install uv

Initialize a new project

mkdir my-python-project && cd my-python-project
uv init
uv venv
source .venv/bin/activate

Add core tools

uv add --dev ruff mkdocs mkdocstrings mkdocstrings-python bump-my-version

Lint & Format

Use ruff for both linting and formatting to keep things simple.

pyproject.toml (ruff)

[tool.ruff]
line-length = 100
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

Run checks

uv run ruff check .
uv run ruff format .

Create Docs

MkDocs + mkdocstrings generates clean docs from your code and docstrings.

Bootstrap docs

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"

Manual release flow

# update version in pyproject.toml
git add pyproject.toml && git commit -m "chore: release v0.2.0"
git tag -a v0.2.0 -m "Release v0.2.0"
git push && git push --tags

Automated bumping (bump-my-version)

[tool.bumpversion]
current_version = "0.1.0"
commit = true
tag = true

[[tool.bumpversion.files]]
filename = "pyproject.toml"

# usage
uv run bump-my-version bump minor   # 0.1.0 -> 0.2.0