Python Developer Tooling Handbook
This is not a book about programming Python. Instead, the goal of this book is to help you understand the ecosystem of tools used to make Python development easier and more productive. For example, this book will help you make sense of the complex world of building Python packages: what exactly are uv, Poetry, Flit, Setuptools, and Hatch? What are the pros and cons of each? How do they compare to each other? It also covers tools for linting, formatting, and managing dependencies.
The handbook is structured according to the Diátaxis framework. There are four primary sections:
- Tutorial: This section provides step-by-step guides to help you get started in improving your Python development experience.
- How To: This section help you get things done in your Python project.
- Explanation: This section provides in-depth explanations to deepen your understanding Python development.
- Reference: This section provides detailed information about specific tools and concepts in Python development.
The book does not attempt to replace the documentation available for various tools; a link to the documentation for each tool is available on its Reference page. Also, the handbook is meant to complement, not replace, the Python Packaging Authority’s excellent Python Packaging User Guide.
This book is a work in progress and will be updated regularly. If you have any suggestions or feedback, please feel free to use the feedback form at the bottom of any page page.
Tim Hopper
Raleigh, North Carolina
Recent Blog Posts
Interview with the Pybites podcast
July 30, 2025
Bob Belderbos invited me on the Pybites podcast where I talked about the handbook, uv, and more. I hope you enjoy it.
Use Interceptors to teach Claude Code to use uv
July 28, 2025
AI coding agents like Claude Code, Cursor, or GitHub Copilot often default to using system Python interpreters instead of using uv.
Armin Ronacher, creator of Flask and Jinja, shared an elegant solution to this problem: creating dummy Python interpreter that actively redirect AI agents toward better tooling choices.
Tip
uvhow: Get uv upgrade instructions for your uv install
July 22, 2025
I’ve released uvhow, a simple command-line tool that detects how uv was installed on your system and provides the correct upgrade instructions.
uv can be installed through multiple methods. When it’s time to upgrade, users often struggle to remember which installation method they used, leading to confusion about the correct upgrade command.
uvhow automatically detects your uv installation method and tells you exactly how to upgrade:
uvx uvhowThe tool works across Windows, macOS, and Linux and supports all major installation methods including:
uv 0.8 Release: Automatic Python Installation to PATH
July 19, 2025
uv 0.8 stabilizes one of the most significant workflow improvements in Python tooling: automatic installation of Python executables to your PATH. This means you can finally install Python versions with uv python install and use them system-wide without wrestling with environment activation.
Python is good now!
July 16, 2025
I love César Soto Valero’s recent post I’m Switching to Python and Actually Liking It.
To my great surprise, I’ve found that Python, and everything around it, has really improved a lot over the last decades.
Here are just three examples:
- Python has created a very complete ecosystem of libraries and tools for processing and analyzing data.
- Python has gotten faster with optimized static compilers like Cython.
- Python has done a good job of hiding its legacy ugliness (such as
__init__,__new__, and similar aberrations), sweetening its syntax to accommodate developers with good taste.
Why isn't Python packaging part of core development?
July 16, 2025
bitecode.dev just posted a massive video interview with Python core dev Brett Cannon. Among many other things, Brett explains why Python packaging hasn’t been part of Python core development:
Basically, they’re separate because Guido doesn’t care about packaging. That’s really what it comes down to. When packaging started to become a thing, we just didn’t have any interest in it, and so it never became a core dev concern. It just never came up—it was just not our thing. So the community in various ways stepped up to fill that void.
Hynek Schlawack's uv Workflow Guide
July 7, 2025
Hynek Schlawack’s new video “uv: Making Python Local Workflows FAST and BORING in 2025” demonstrates practical uv workflows using real examples.
He covers:
- Replacing pip/virtualenv/pyenv with a single tool
- Dependency management and lock files
- Testing and linting integration
justintegration for cross-platform commands
If you missed Part 1 of Hynek’s series, it’s available here.
The uv build backend is now stable
July 3, 2025
For about a year, uv has had a uv build command for generating distributable wheels and source distributions on pypi and elsewhere.
However, uv has relied on other tools for the build backend, i.e. the actual piece constructing the wheel or sdist as defined by PEP 517. By default, uv uses hatchling as the build backend.
As of this week, the uv team has now declared the uv build backend as stable and, most notably, really, really fast. Charlie Marsh’s benchmarks suggest that it’s 10 to 35 times faster than flit, hatchling, and setuptools. While I’ve never really needed my package builds to be faster, I’ve learned that faster tools often enable new things I didn’t imagine possible; I’m interested to see what those might be here.
Managing Python Versions In Your uv Projects
June 25, 2025
One of the many ways the package manager uv has changed Python is by making it painless to install and run different versions of the Python interpreter.
That said, I’ve occasionally gotten tripped up configuring this correctly in my development environments. I’ve written a few articles to try to clarify things:
- What is a .python-version file? Not unique to uv, a .python-version file specifies which Python version should be used for a particular project or directory.
- .python-version vs requires-python in pyproject.toml. The former is for development environments, while the latter is for package metadata.
- How to change the python version of a uv project. If
uv runisn’t using the version of Python you expected or wanted, here is what you can do.
The goal of the handbook is to help you understand the ecosystem of tools used to make Python development easier and more productive. What are some missing topics you’d like to see included?
Comparison of the Two New Typecheckers
May 28, 2025
At PyCon 2025’s Typing Summit, participants were given a first look at Meta’s Pyrefly and Astral’s ty, two new Python type checkers that promise dramatically faster, more powerful type analysis.
Edward Li helpfully took notes and provided a right-up.
Here are some takeaways:
Both tools are blazingly fast
- Pyrefly claims up to 1.8 million lines/sec (35× faster than Pyre, 14× faster than MyPy/Pyright), while ty benchmarks show it running 2–3× faster than Pyrefly on real-world codebases.
The tools have distinct philosophies