Python Developer Tooling Handbook – Uv

What Reddit taught me about why people switch to uv

Tim Hopper — Mon, 27 Apr 2026 09:00:00 -0400

A thread titled “But really, why use uv?” landed on r/Python and pulled 476 upvotes. The original poster wasn’t antagonistic. They used Python casually, installed packages two or three times a month, and couldn’t see why uv was worth adding to a setup that already worked.

The comments convinced them. Reading through the top responses surfaces something the standard uv pitch misses: the compelling case for casual users is not the same as the compelling case for power users.

Did pip 26 close the gap with uv?

Tim Hopper — Fri, 24 Apr 2026 09:00:00 -0400

pip 26.0 closed two of uv’s clearest feature gaps in January: PEP 723 script installs and a datetime-based package filter that mirrors uv’s --exclude-newer. The October 2025 Hacker News thread that kept circling back to “pip has quietly caught up” now reads less contrarian than it did at the time, and the OpenAI acquisition of Astral in March changes the “is this safe to depend on” calculus at the same time.

Review pip’s 2025 to 2026 releases

Four pip releases have landed since April 2025, and the first three narrowed gaps uv was best known for:

How Astral Uses Its Own Tools

Tim Hopper — Thu, 23 Apr 2026 09:00:00 -0400

Astral runs ruff, uv, and ty inside the repos that build them. Their pyproject.toml, .pre-commit-config.yaml, and CI files are public, and a walk through the three shows how the people making ruff, ty, and uv wire their own toolchain into the projects that produce it.

Build ty from source and type-check Python with it

The ruff repository ships ty as part of its crate tree. Three CI steps build ty from source and run it against the repo’s own Python:

uv won developer hearts. Now it has to win READMEs.

Tim Hopper — Tue, 14 Apr 2026 09:00:00 -0400

uv ranked as the most admired technology in Stack Overflow’s 2025 Developer Survey at 74%. A recent analysis by Andrey Aleyan of the top 100,000 Python repositories on GitHub put uv adoption (measured by the presence of uv.lock) at roughly 10%. The gap between “developers love this” and “developers ship this” is wider than any tooling story in recent memory.

Aleyan’s diagnosis is that AI coding agents are the bottleneck: their training data is overwhelmingly pip install -r requirements.txt, so they emit pip install -r requirements.txt. That diagnosis is correct but incomplete. Adoption is bottlenecked by three reinforcing forces, and the AI-agent story is only one of them.

How uv Solves Dependencies So Fast

Tim Hopper — Thu, 09 Apr 2026 00:00:00 +0000

Tip

Want more on uv? Browse every uv tutorial, how-to, reference, and explanation on the uv topic page.

Python dependency resolution is NP-hard in the formal sense: it reduces to Boolean satisfiability. In a Jane Street tech talk (YouTube), Charlie Marsh walked through why uv’s resolver has to solve this problem and the architectural decisions that let it do so 10-100x faster than pip.

OpenAI to Acquire Astral

Tim Hopper — Thu, 19 Mar 2026 00:00:00 +0000

OpenAI announced today that it will acquire Astral, the company behind uv, Ruff, and ty. The Astral team will join OpenAI’s Codex group after the deal closes, subject to regulatory approval.

What this means for Codex

Codex, OpenAI’s coding agent, has grown to over 2 million weekly active users, with 3x user growth and 5x usage increase since the start of 2026. Acquiring Astral gives OpenAI direct ownership of tools that millions of Python developers already depend on. OpenAI plans to integrate Astral’s tools more deeply into Codex so the agent can interact with the toolchain developers already use.

Charlie Marsh on uv, Coding Agents, and the Changing Open Source Contract

Tim Hopper — Tue, 24 Feb 2026 12:00:00 -0500

Charlie Marsh (founder of Astral, creator of ruff, uv, and ty) joined Michael Chow and Wes McKinney on The Test Set. They covered uv’s adoption strategy, how coding agents are changing Astral’s development process, and what’s happening to open source when writing code becomes cheap.

uv’s compatibility layer was the point

When uv first shipped, it only had uv pip install and uv venv. Some people found this odd. Charlie says it was deliberate:

FOSDEM Talk: Modern Python Monorepo with uv, Workspaces, and prek

Tim Hopper — Thu, 05 Feb 2026 08:00:00 -0500

Jarek Potiuk, Apache Airflow PMC member and the project’s top committer, gave a talk at FOSDEM 2026 on how Airflow manages its massive Python monorepo. The recording is now available.

Airflow ships over 120 separate Python distributions from a single repository, with 700+ dependencies and 3,600+ contributors. That scale forced the team to modernize their tooling. The talk walks through how they did it.

uv Workspaces for Monorepo Management

The new setup centers on uv workspaces. Rather than splitting 120 distributions across separate repositories or bundling everything into an unmanageable monolith, Airflow uses uv’s workspace feature to let distributions depend on each other via local sources instead of pulling from PyPI.

uvx.sh: Install Python tools without uv or Python

Tim Hopper — Thu, 22 Jan 2026 12:00:00 -0500

Astral has released uvx.sh, a service that generates installation scripts for any Python tool on PyPI. With a single curl or PowerShell command, users can install tools like ruff or pytest without having uv or Python already installed on their system.

How It Works

uvx.sh dynamically generates installation scripts for any PyPI package. The URL pattern is simple:

uvx.sh/{package}/install.sh     # macOS/Linux
uvx.sh/{package}/install.ps1    # Windows

For example, to install ruff:

How uv Achieved Its Performance

Tim Hopper — Fri, 26 Dec 2025 18:00:00 +0000

Andrew Nesbitt’s “How uv got so fast” explains that uv’s speed comes less from Rust and more from eliminating work entirely.

Speed Through Elimination

Rather than optimizing slow code paths, uv just removes them:

No .egg support
No pip.conf
No bytecode compilation by default
Ignoring requires-python upper bounds reduces resolver backtracking

Rust-Independent Optimizations

Many of uv’s performance gains could work in pip:

Parallel downloads instead of sequential
Smart HTTP range requests for metadata

uv got fast by launching when PEP 658 infrastructure was ready and by skipping backward compatibility requirements that slow down pip.

Teaching LLMs Python Best Practices

Tim Hopper — Fri, 21 Nov 2025 09:00:00 -0500

Large language models possess extensive Python knowledge from training data, yet they consistently struggle with modern tooling practices. Despite being trained on massive amounts of Python code, frontier models often default to outdated patterns like direct python or pip commands instead of using virtual environments and modern tools like uv.

how is it, that despite every frontier LLM being insanely python maxxed they rarely use virtural envs, and even adding rules like "we are using uv, do everything with uv" they ignore it and think the system python is broken. like, every time. that's actually an accomplishment

Claude Code Hooks for uv Projects

Tim Hopper — Tue, 11 Nov 2025 06:00:00 -0500

Claude Code supports custom hooks that guide the AI agent toward project-specific workflows. For Python projects using uv, hooks can prevent Claude from falling back to pip and python commands.

Note

This post builds on the interceptor approach for teaching AI agents about uv. Interceptors provide runtime feedback; hooks prevent problematic commands before execution.

Sync with uv: Eliminate Pre-commit Version Drift

Tim Hopper — Fri, 26 Sep 2025 15:01:00 -0400

anaging tool versions across multiple configuration files creates persistent headaches in Python development. When you upgrade ruff in your pyproject.toml, you must remember to manually update the pre-commit hook version in .pre-commit-config.yaml. This version drift causes inconsistent behavior between local development and pre-commit checks.

The sync-with-uv library solves this by automatically synchronizing tool versions between uv’s lockfile and .pre-commit-config.yaml.

The Problem

Consider this common scenario:

# pyproject.toml
[dependency-groups]
lint = ["ruff>=0.1.0", "mypy>=1.0.0"]

# .pre-commit-config.yaml
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.1.5  # Must manually sync with pyproject.toml
  hooks:
    - id: ruff

When uv lock --upgrade updates ruff to 0.1.8, the pre-commit hook stays pinned to 0.1.5. This creates confusing behavior where local checks differ from pre-commit results. The same gap applies to mypy and any other tool pinned in both files.

uv format: Code Formatting Comes to uv (experimentally!)

Tim Hopper — Thu, 21 Aug 2025 16:08:00 -0400

The latest uv release (0.8.13) quietly introduced an experimental new command that Python developers have been waiting for: uv format. This addition brings code formatting directly into uv’s toolkit, eliminating the need to juggle multiple tools for basic Python development workflows.

What is uv format?

The uv format command provides Python code formatting through uv’s interface. Under the hood, it calls Ruff’s formatter to automatically style your code according to consistent standards.

How Python's RFC Process Paved the Way for uv, Ruff, and Ty

Tim Hopper — Fri, 01 Aug 2025 15:22:00 -0400

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 stems partly from Astral’s attention to guidelines established by the Python Enhancement Proposal (PEP) process over the last twenty-five years.

Interview with the Pybites podcast

Tim Hopper — Wed, 30 Jul 2025 09:20:00 -0400

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

Tim Hopper — Mon, 28 Jul 2025 09:34:00 -0400

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

Tim Hopper — Tue, 22 Jul 2025 20:18:00 -0400

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 uvhow

The tool works across Windows, macOS, and Linux and supports all major installation methods including:

uv 0.8 Release: Automatic Python Installation to PATH

Tim Hopper — Sat, 19 Jul 2025 09:27:00 -0400

[!TIP]

Check out our guide to upgrading uv

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.

Global Python Access Without the Hassle

The headline feature addresses a long-standing frustration in Python development. When you run:

Python is good now!

Tim Hopper — Wed, 16 Jul 2025 13:43:00 -0400

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.

Read the whole post.

Hynek Schlawack's uv Workflow Guide

Tim Hopper — Mon, 07 Jul 2025 10:21:00 +0000

{< youtube TiBIjouDGuI >}}

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
just integration for cross-platform commands

If you missed Part 1 of Hynek’s series, it’s available here.

The uv build backend is now stable

Tim Hopper — Thu, 03 Jul 2025 01:29:29 +0000

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

Tim Hopper — Wed, 25 Jun 2025 10:09:00 +0000

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:

How to install Python with uv. Before you can pin a Python version, you need to have it installed.
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 run isn’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?

Why uv makes Make less essential for Python projects

Tim Hopper — Fri, 04 Apr 2025 00:00:00 +0000

or years, I’ve been a strong advocate for using Makefiles in Python projects. They’ve provided a consistent interface for common tasks like environment setup (make venv), testing (make test), and code formatting (make format).

But with the advent of uv, I’m reconsidering this approach. Make might be becoming less essential in the modern Python ecosystem.

The Speed Factor

One of Make’s traditional strengths is avoiding unnecessary work. A properly configured Makefile only rebuilds targets when dependencies change. This was valuable when setting up Python environments, for example:

The Python Tooling Revolution

Tim Hopper — Wed, 02 Apr 2025 16:48:00 +0000

Python development is experiencing a tooling revolution thanks to Astral’s ruff and uv. Lewis Gaul’s blog examines how these tools are transforming Python workflows with exceptional speed and intelligent design.

When trying ruff check the benefits were immediately obvious: performance is incredible, provides a superset of the pylint rules, reporting of errors is very clear, configuration is straightforward, documentation is excellent…and above all else the –fix flag is a huge win to automatically fix certain rule violations.

Simple, Modern Python

Tim Hopper — Tue, 01 Apr 2025 00:00:00 +0000

Joshua Levy recently shared his enthusiasm for uv, Astral’s Python package manager, along with a practical template for new projects using this tool. His thread on X highlights both technical advantages and philosophical approaches to modern Python development.

Key Points from Levy’s UV Template

Levy has created a simple-modern-uv, Copier template that combines minimal but essential tools for Python projects:

Uses uv for package management
Incorporates ruff for linting and formatting (replacing Black and isort)
Includes mypy, codespell, and pytest
Provides GitHub Actions configuration
Uses Copier for template management

Why uv Matters Beyond Speed

While uv’s performance is impressive, Levy emphasizes that its real value lies in dependency management fundamentals:

Dependabot Now Supports uv

Tim Hopper — Fri, 14 Mar 2025 09:26:00 +0000

As of March 13, 2025, Dependabot officially supports uv.

Dependabot monitors repositories for outdated or insecure dependencies and creates pull requests to update them. GitHub’s tool supports npm, pip, Maven, Docker, and now uv.

Why Doesn't the Authoritative Python Packaging Guide Mention the Best Thing that's Happened to Python Packaging?

Tim Hopper — Thu, 27 Feb 2025 14:56:00 +0000

Despite uv’s meteoric rise and widespread adoption in the Python community over the last year, the excellent and official Python Packaging User Guide (PPUG) at packaging.python.org makes no mention of it. Understanding why this is requires some background knowledge and unveils understanding of the modern Python developer tooling ecosystem.

uv’s Rise

Since its introduction in early 2024, uv has rapidly gained traction as a high-performance alternative to existing Python tooling. uv delivers 10-100x faster package operations than traditional tools while consolidating functionality previously spread across multiple utilities (pip, pip-tools, virtualenv, pyenv, and more). Its performance advantages, cross-platform support, and unified approach have made it increasingly popular among Python developers.

Why Doesn't the Authoritative Python Packaging Guide Mention the Best Thing that's Happened to Python Packaging?

Tim Hopper — Thu, 27 Feb 2025 14:56:00 +0000

uv is the most widely adopted new Python tool in years, yet the Python Packaging User Guide (PPUG) makes no mention of it.

What does uv replace?

uv delivers 10-100x faster package operations than pip while consolidating functionality previously spread across pip-tools, virtualenv, pyenv, and more into a single tool. Since its introduction in early 2024, it has become the default recommendation in many Python teams and communities.

Who controls packaging.python.org?

The Python Packaging Authority (PyPA) started in 2011 as a working group focused on maintaining specific packaging tools, particularly pip and virtualenv. Its name suggests broad authority over Python packaging, but its scope has always been narrower.

Production Experiences with uv

Tim Hopper — Wed, 26 Feb 2025 08:48:00 +0000

Yesterday on Reddit, batman-iphone asked:

Anyone used uv package manager in production

Is it reliable to use it in production as it is comparatively new in the market.

Also, are there any disadvantages that I should be aware of before pitching it to my manager?

Given that the tool was introduced just over a year ago, its rate of adoption has been wild.

Here is my summary of the discussion:

uv Pros

Real Performance Gains

Multiple developers reported dramatic performance improvements, e.g.,

Why Use uv Projects Instead of requirements.txt?

Tim Hopper — Wed, 19 Feb 2025 09:17:00 +0000

This is an excerpt from the forthcoming Python Developer’s Tool Handbook. The handbook provides comprehensive guidance on Python tooling and best practices for modern Python development.

The Python ecosystem offers two main approaches to managing project dependencies: the traditional requirements.txt file and the newer pyproject.toml standard. Understanding the strengths and limitations of each helps inform better choices for Python development.

bitecode.dev's "A year of uv"

Tim Hopper — Tue, 18 Feb 2025 09:53:00 +0000

uv hit its one-year mark, and bitecode.dev published a thorough retrospective on how it’s held up.

The highlights:

Solves Python bootstrapping by installing without Python and working the same across platforms
Fast - tasks that took minutes now take seconds
More reliable dependency resolution than alternatives
Works with existing tools without friction
Error messages tell you what went wrong and what to do

The article lists five situations where uv might not fit, but these feel overly cautious. Speed, reliability, and simpler workflows make uv worth adopting for any team that can.

Flexible Python Version Management with uv and tox

Tim Hopper — Wed, 12 Feb 2025 10:20:00 +0000

When working with Python projects that use tox for testing, you may encounter version mismatch errors like:

lint-format: skipped because could not find python interpreter with spec(s): python3.8

This happens when tox expects a specific Python version that isn’t available in your environment. Traditionally, this would require:

One Line Command to Launch a Notebook with Pytorch

Tim Hopper — Wed, 15 Jan 2025 14:18:00 +0000

uv is changing how accessible Python is for new users.

If you want to try out pytorch in a Jupyter Notebook, you can install uv and then run this single line command:

uv run --python 3.12 --with "torch~=2.4" --with jupyter --with "numpy<2" jupyter lab

uv will grab all your dependencies (including Python 3.12, if you don’t have it installed), install them in an isolated environment, and launch Jupyter Lab.

"uv: Towards a unified vision for Python tooling"

Tim Hopper — Fri, 27 Dec 2024 10:49:00 +0000

This is a great post](https://thedataquarry.com/posts/towards-a-unified-python-toolchain/) by Prashanth Rao on the unified vision that uv brings for Python package and project management. As he shares, the tools in this space have been improving over the last 15 years, but uv is a step-change for usability.

The most remarkable aspect of uv is the list of steps he shares that (might) happen when you call uv run hello.py:

Installs Python if it’s not already installed

Creates and activates the virtual environment

Installs the dependencies

Runs the code

And all of this happens with blazing speed.

Effective Python Developer Tooling in December 2024

Tim Hopper — Fri, 20 Dec 2024 19:25:00 +0000

I have been writing Python for 14 years next month. When I started, people were still using easy_install to install egg-based packages for Python 2.7 and nobody had heard about Conda yet, much less uv. The Python tool ecosystem has changed since. Many people are confused by the fragmentation in the ecosystem, but we have better tooling for Python today than we’ve ever had before.

A friend recently invited me to give a talk to his team about Python tooling. In the presentation, I shared some principles of Python tooling and developer efficiency, some anti-patterns I’ve observed, recommended practices, and an opinionated list of tools I like in December 2024. What follows is a summary of that talk.

uv 0.3: One command line to rule them all (almost)

Tim Hopper — Wed, 21 Aug 2024 09:30:00 +0000

Yesterday, Charlie Marsh and his team at Astral released uv 0.3.0.

For those who may have missed it, uv was released earlier this year primarily as a blazing-fast replacement for pip for installing Python packages.

This new release provides new documentation and a host of new functionality.

Charlie Marsh and Simon Willison have written helpful posts about the new functionality.

I thought it’d be helpful to illustrate how the current uv functionality compares to existing tools:

uv Command	Alternative to
uv pip	pip and pip-tools
uv venv	venv and virtualenv
uv tool	pipx
uv init	Poetry/PDM (partially)
uv python	pyenv
uv run	nothing!

uv only partially replicates Poetry and PDM because it has yet to implement package building and publishing, only project management. However, they provide simple commands for publishing using existing tools and a uv project.

uv got to keep up: a new installer announced!

Tim Hopper — Fri, 16 Feb 2024 01:29:29 +0000

Astral, Charlie Marsh’s company best known for Ruff, announced uv today, “an extremely fast Python package installer and resolver, written in Rust.” uv is intended as a “drop-in replacement for pip and pip-compile.”

Some early feedback looks very encouraging, e.g.,

It looks like uv will bring dependency install times for @dagster down from 1m26s to 18s, and a blistering 29ms with cache!https://t.co/z7MXOFKbiw

Amazing work @charliermarsh and team!
— colton (@coltonpadden) February 15, 2024

I just swapped a Docker image from "pip install --no-cache-dir -r requirements.txt" to "uv pip install --no-cache -r requirements.txt" and the build time went from 67.8s to 15.4s. Absolutely insane. https://t.co/VwOIfIpnQP

Quick start guide for Python development on a Mac

Tim Hopper — Mon, 05 Feb 2024 00:00:00 +0000

Note

For a modern approach, consider uv, which handles Python installation, project management, and dependency management in a single tool. The pyenv + Poetry workflow described below remains valid, but uv offers a more streamlined experience.