Every Python project I start now begins with the same set of tools, and the setup ends with a repo that formats itself, lints itself, types itself and tests itself. This post is a shortcut: follow along to the end and your project will be set up as smoothly as mine, without iterating over messages in an AI chat to get there (and you save the tokens too ;).

uv sits on top of the project and every command goes through that one tool.

Before uv and After uv

1. Before uv: The stack we used to need

Python packaging was never a one-tool thing. It was always a bunch of overlapping tools, each with its own config file and its own failure mode.

The hassle of calling multiple tools was already there. On top of that, you followed a long list of instructions instead of a few commands under one tool — and still ended up with two machines running different environments.

Then, uv comes to the rescue 😎.

2. After uv: What uv has to offer

uv is one Rust binary from Astral that does all six jobs (and many more), and it offers peace of mind to developers 😆.

There are a few other things worth noticing about it, and they're why I switched.

1. Installing and resolving takes seconds, not minutes. Speed in project initialization always fascinates developers.

2. With uv, you don't need to activate a virtual environment. uv run syncs the environment and executes in it.

3. .python-version pins the Python version and downloads it.

4. Last but not least, everything lives in pyproject.toml.

And the caveats I want to consider about uv:

1. It is still pre-1.0 (0.12.x at the time of writing), and it matures with every release. It's stable and widely used in production, although the version number might make you skeptical.

2. It does not replace conda for non-Python binaries such as CUDA toolkits, some scientific C/Fortran stacks, etc.

Now, let's move on to the project setup.

Follow along.

The Fundamental Toolchain

Five tools. Each one does exactly one job, and every one of them is configured in pyproject.toml.

1. uv

The 2026 default. One tool for Python versions, environments, dependencies and lockfiles. 10–100× faster; a uv.lock makes your build reproducible.

1. Install

   curl -LsSf https://astral.sh/uv/install.sh | sh      # macOS / Linux
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows
   

2. Verify

   uv --version
   uv self update
   

   Worth doing once:

   uv generate-shell-completion zsh >> ~/.zshrc   # or bash / fish / powershell
   

3. Get a Python

   Self-contained Python builds live in uv's own directory and won't touch system Python.

   uv python list              # what's available and what's installed
   uv python install 3.14      # download a standalone build
   uv python find              # which one would be used here
   

4. Initialize a Project

   uv init myapp  # use your project name instead of 'myapp'
   # OR
   uv init --app --package myapp
   
   # this command creates a packaged app: src/ + entry point (default)
   

   Project structure after uv init:

   myapp/
   ├── .git/
   ├── .gitignore
   ├── .python-version
   ├── README.md
   ├── pyproject.toml
   └── src/myapp/
       └── __init__.py
   

   Initialize library project:

   uv init --lib mylib  # use your library name instead of 'mylib'
   
   # this command creates a library: src/ + py.typed, no entry point
   

   Then the project structure will be:

   mylib/
   ├── .git/
   ├── .gitignore
   ├── .python-version              # e.g. 3.14
   ├── README.md
   ├── pyproject.toml
   └── src/
       └── mylib/
           ├── __init__.py          # def hello() -> str: ...
           └── py.typed             # empty marker file
   

5. Explore .python-version

   3.14
   

6. Explore pyproject.toml

   [project]
   name = "myapp"
   version = "0.1.0"
   description = "Add your description here"
   readme = "README.md"
   authors = [
       { name = "your-username", email = "your-email@example.com" }
   ]
   requires-python = ">=3.14"
   dependencies = []
   
   [project.scripts]
   myapp = "myapp:main"
   
   [build-system]
   requires = ["uv_build>=0.12.5,<0.13.0"]
   build-backend = "uv_build"
   

After the project has been initialized, let's move on to linting and formatting.

2. ruff

One more Rust binary from Astral, and it wears two hats: linter and formatter. This single tool retires black, flake8 (and its dozen plugins), isort, pyupgrade and pydocstyle — one config block instead of five dotfiles.

1. Add it

   uv add --dev "ruff>=0.16.4,<0.17"   # lands in [dependency-groups] dev, explore pyproject.toml
   uv run ruff --version
   

2. Configure it

   Everything goes in pyproject.toml.

   # ruff
   [tool.ruff]
   extend-exclude = ["migrations", "notebooks"]
   indent-width = 4
   line-length = 80
   required-version = ">=0.16,<0.17"
   show-fixes = true
   src = ["src", "tests"]
   
   [tool.ruff.lint]
   dummy-variable-rgx = "^_.*$" # underscore-prefixed names are intentionally unused
   ignore = [
     "D203",
     "D213", # the two pydocstyle rules that fight each other
     "E741", # ambiguous names — comes back once you select all of "E"
   ] 
   select = [
     "E",
     "F",
     "I",
     "UP",
     "B",
     "SIM",
     "RUF", 
     "D",
     "ANN",
     "S",
     "PTH", 
     "C901",
     "PLR0913", 
   ] 
   unfixable = ["F401", "F841"] # flag unused imports/vars, don't silently delete them 
   
   [tool.ruff.lint.isort]
   combine-as-imports = true
   known-first-party = ["myapp"]
   
   [tool.ruff.lint.mccabe]
   max-complexity = 10 # branches per function before ruff says "split this"
   
   [tool.ruff.lint.pylint]
   max-args = 7 # parameters per function; self/cls don't count
   
   [tool.ruff.lint.per-file-ignores]
   "__init__.py" = ["F401"] # re-exports aren't unused
   "tests/**/*.py" = ["S101", "D", "ANN"] # asserts are fine in tests
   
   [tool.ruff.lint.pydocstyle]
   convention = "google" # or numpy
   
   [tool.ruff.format]
   docstring-code-format = true # formats code inside your docstrings too
   docstring-code-line-length = "dynamic" 
   indent-style = "space" 
   line-ending = "lf" # stops CRLF noise in diffs on Windows
   quote-style = "double" 
   skip-magic-trailing-comma = false # keep false: your trailing comma forces the split
   

3. Run it

   uv run ruff check .           # lint
   uv run ruff check . --fix     # apply the safe fixes
   uv run ruff format .          # format
   

   Order matters: check --fix → format. Fixes can leave lines that need re-wrapping.

3. mypy

Ruff checks that an annotation exists; mypy checks that it isn't lying. A function that promises -> User but quietly returns None runs fine today and explodes at user.email three weeks from now — mypy catches it before you commit.

def get_user(user_id: int) -> User:
    return db.query(user_id)   # actually returns User | None

Ruff is happy with this; mypy is not.

1. Add it

   uv add --dev "mypy>=2.3,<3"
   uv run mypy --version
   

2. Configure it

   # mypy
   [tool.mypy]
   python_version = "3.14"       # mypy does NOT read requires-python — set it here
   files = ["src", "tests"]
   strict = true                 # ~15 flags at once; start here on a new project
   warn_unreachable = true       # not in strict, but catches real bugs
   pretty = true
   
   # per-module escape hatches — note the DOUBLE brackets (array of tables)
   [[tool.mypy.overrides]]
   module = ["tests.*"]
   disallow_untyped_defs = false
   
   [[tool.mypy.overrides]]
   module = ["some_untyped_lib.*"]
   ignore_missing_imports = true   # scope this per-module, never globally
   

3. Run it

   uv run mypy              # uses `files` from the config
   uv run mypy src/myapp    # or point it somewhere specific
   

4. pytest

pytest is the test runner. You write the tests; it finds them, executes them, and reports what broke.

1. Add it

   uv add --dev "pytest>=9.1,<10" pytest-cov
   uv run pytest --version
   

2. Configure it

   # pytest
   [tool.pytest.ini_options]
   testpaths = ["tests"]          # don't scan .venv, don't scan src
   addopts = [
       "-ra",                     # summary of everything that wasn't a plain pass
       "--strict-markers",        # a typo'd marker is an error, not a silent skip
       "--strict-config",         # a typo'd config key here is an error too
       "--import-mode=importlib", # modern import mode; no __init__.py in tests/
   ]
   xfail_strict = true            # an xfail that passes is a failure, not a shrug
   filterwarnings = ["error"]     # deprecation warnings fail the suite
   markers = [
       "slow: takes more than a second",
       "integration: touches the network or a real DB",
   ]
   
   [tool.coverage.run]
   source = ["src"]
   branch = true          # was every if/else arm taken, not just every line
   
   [tool.coverage.report]
   exclude_also = [       # `also`, not `exclude_lines` — that one replaces the defaults
       "if TYPE_CHECKING:",
       "raise NotImplementedError",
   ]
   

3. Run it

   uv run pytest                  # everything
   uv run pytest -x               # stop at first failure
   uv run pytest --lf             # only what failed last time
   

5. pre-commit

pre-commit wires the other four tools to git commit, so the repo enforces its own standards instead of trusting your discipline at 1am.

1. Add it

   uv add --dev pre-commit
   

2. Configure it

   Create .pre-commit-config.yaml, next to pyproject.toml:

   fail_fast: true    # stop at the first failing hook
   
   repos:
     - repo: https://github.com/pre-commit/pre-commit-hooks
       rev: v6.0.0
       hooks:
         - id: trailing-whitespace
         - id: end-of-file-fixer
         - id: check-toml
         - id: check-yaml
         - id: check-merge-conflict
         - id: check-added-large-files
   
     - repo: https://github.com/astral-sh/uv-pre-commit
       rev: 0.12.5
       hooks:
         - id: uv-lock          # keeps uv.lock in sync with pyproject.toml
   
     - repo: https://github.com/compilerla/conventional-pre-commit
       rev: v4.4.0
       hooks:
         - id: conventional-pre-commit
           stages: [commit-msg]
   
     # local hooks run against the uv-locked environment, so uv.lock is the
     # single source of truth for tool versions — no second `rev:` pin to drift.
     - repo: local
       hooks:
         - id: ruff-check
           name: ruff check
           entry: uv run ruff check --fix
           language: system
           types_or: [python, pyi]
   
         - id: ruff-format
           name: ruff format
           entry: uv run ruff format
           language: system
           types_or: [python, pyi]
   
         - id: mypy
           name: mypy
           entry: uv run mypy
           language: system
           types: [python]
           pass_filenames: false   # mypy needs the whole package, not staged files
   
         # pre-push, not pre-commit: the full suite is worth blocking a push over,
         # but running it on every single commit is what gets --no-verify'd once
         # the suite grows.
         - id: pytest
           name: pytest
           entry: uv run pytest
           language: system
           pass_filenames: false
           stages: [pre-push]
   

   Now install hooks:

   uv run pre-commit install --install-hooks \
     --hook-type pre-commit --hook-type pre-push --hook-type commit-msg
   

3. Run it

   uv run pre-commit run --all-files   # first time: fix the whole repo at once
   uv run pre-commit run               # just the staged files (what the git hook does)
   

Explore further

Five tools is the setup. Here's what I'd read about next, and why — depending on what the project turns into.

1. uv build and uv publish — the two commands from the table at the top this post never used. A tag-triggered CI job turns a release into git tag v0.1.0 && git push --tags. Read up on trusted publishing: no API token in your repo secrets.

2. pydantic-settings — a runtime dependency, not dev tooling. Scattered os.environ calls become one typed, validated object that fails at startup instead of at 3am.

3. structlog — print() doesn't survive production and logging is configured by ritual. Structured JSON logs your aggregator can query.

Your Daily Cheatsheet

The setup is one-time cost. There will be moments where you will need these commands.

1. Add or update package

   uv add <package-name>    # runtime dependency
   uv add --dev <package-name>    # dev tool/dependency
   uv remove <package-name>    # uninstall/drop dependency
   uv lock --upgrade-package <package-name>    # upgrade one package
   uv lock --upgrade    # upgrade all
   uv sync    # when you see change in lockfile
   

2. After you write some code
   Always remember to run in order.

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

3. Before you commit

   uv run pre-commit run
   

Conclusion

Five tools, one config file, and a repo that formats, lints, types and tests itself without being asked. The setup takes twenty minutes once and then gets out of your way for the life of the project.

Start with uv init, add the rest as you need them — none of this has to land on day one. And if your pyproject.toml ends up looking nothing like mine, good. It's yours.

Good luck. 😃 👋.