Tools to setup great python projects (2025 update)

Reference code for the talk: Tools to setup great python projects (2025 update), by Duarte Pompeu. You may also be interested in:

• slides used in the talk
• stream (unfortunately it has audio issues)
• article: the written version of the talk
• VOD: soon?

Includes:

• cheatsheet (bottom of README)
• script to setup a minimal project with these tools: setup.sh
• script to run all checks: checks.sh

Note: I'm not including the lock file in this repo because it can get stale, but it's usually a good idea to also version control it (except if you're working in a re-usable lib, where you may want users to have flexibility in versioning).

Configuration

I always recommend that you configure these tools in pyproject.toml. Tools will look into it by default, and this has nice advantages:

• reduces config drift
• running from the CLI is really simple, eg uv run ruff check will automatically apply all the rules

What usually happens when you don't centralize the configs:

• extra effort: need to specify configs in scripts, IDE, CI/CD, always type them when running in CLI
• config drif: if you want to change any configuration, and you forget to change it everywhere, it leads to drift and annoyances, eg CI/CD enforcing different rules than your local checks

Checks

Script

If you want to keep it simple, you can store the commands in a script, that can be used by devs and CI/CD.

bash scripts/checks.sh

Pre-commit

You can also use pre-commit instead of shell scripts. With pre-commit, I recommend that you always use language: system and let uv manage your tools, reducing duplicate efforts and configuration drifs.

# run manually
uvx pre-commit run -a
# install as as a git hook (applies automatically when committing)
uvx pre-commit install

Cheatsheet

uv

# install
curl -LsSf https://astral.sh/uv/install.sh | sh

# initialize project
cd <project-folder>
uv init --python 3.13

# install packages (usually automatic)
uv sync

# run your programs
uv run python hello.py

# add packages
uv add requests
uv add pytest --dev
# TODO: editable mode
# TODO: github packages

# update packages (and their sub-dependencies)
uv add requests --upgrade

# remove packages
uv remove requests

# lock packages (usually automatic)
uv lock
uv export > requirements.txt

ruff

If we define the configs for ruff in pyproject.toml, these commands will apply them automatically:

# format code
uv run ruff format

# lint with safe auto-fixes
uv run ruff check --fix --show-fixes

reorder-python-imports

TODO: define files in pyproject.toml!

uv run reorder-python-imports --py312-plus --application-directories src:tests

pytest

If we define the configs for pytest in pyproject.toml, these commands will apply them automatically:

uv run pytest