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. Also, be sure to check out the helpful Scientific Python Library Development 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
ty's Breakthrough: Why Incremental Analysis Matters for Python
August 11, 2025
In a recent PyBytes podcast interview, Astral’s Charlie Marsh shared insights into what makes their new type checker ty unique and how it aims to address longstanding challenges in Python type checking.
What is ty?
ty serves dual purposes: it functions as a standalone command-line type checker (similar to mypy) and as a language server that powers IDE features like go-to-definition, code completion, and real-time diagnostics.
“We wanted to build a great type checker and a great language server, and they have things that are in common but they also have very different requirements,” Marsh explained. “If you don’t think about both of those from the start, you end up in a little bit of trouble.”
How Python's RFC Process Paved the Way for uv, Ruff, and Ty
August 1, 2025
Astral, an independent startup, has taken the Python world by storm over the last few years with three fast, robust Python developer tools:
- ruff (linter and formatter)
- uv (packaging and project management)
- ty (static type checker, still under development)
These tools came from the mind of Charlie Marsh, who is neither a Python core developer nor directed by the Python Steering Council. While being independently developed, these tools work seamlessly within the established Python ecosystem. This success is in part due to Astral’s attention to the guidelines extablished by the Python Enhancement Proposal (PEP) process over the last twenty-five years
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.