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

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.

Force one: the agents read what we wrote

Coding agents don’t reason about packaging from first principles. They pattern-match against fifteen years of GitHub history, and that history is a wall of pip install. Even when a project’s CLAUDE.md or AI-assistant rules say “use uv,” the agent will still reach for python -m pip when the surrounding code looks like a 2018 project layout.

The handbook documents two fixes for this force. The blunt option is the interceptor pattern, which installs fake python and pip shims that hard-fail with a message telling the agent to use uv. The configuration-file option uses per-tool guides for Claude Code, Cursor, and the generic AI-assistant setup guide. Both work inside a project, but neither scales to ecosystems you don’t control.

Force two: the official guide doesn’t mention uv

A new Python developer who searches “how do I install a package” lands on the Python Packaging User Guide. The PPUG mentions pip, virtualenv, hatch, flit, pdm, and Poetry. It does not mention uv. Two years after uv shipped and a year after it became the default recommendation in most modern Python teams, the canonical install instructions on packaging.python.org still walk readers through python -m venv, source .venv/bin/activate, and pip install.

The handbook covers why this is. In short, the PyPA is structurally a maintainer collective for specific projects (pip, virtualenv, setuptools), not a neutral standards body for “the best Python tool today.” The result is that every newcomer’s first install is shaped by the tools the PyPA happens to maintain, regardless of which tool the rest of the ecosystem has chosen.

Force three: every README installs with pip

This is the force Aleyan’s piece points at indirectly and the one with the lowest cost to fix. Walk through the README of any popular Python library (FastAPI, Pydantic, httpx, Polars, scikit-learn) and the install section opens with pip install <package>. A uv user has to translate. An AI agent reading the README copies the pip command verbatim. A Stack Overflow answer copying from the README perpetuates it. Every library’s “installation” section is a vote for which tool its users will reach for next.

This force feeds force one, because agents emit pip in part because READMEs say pip. Fixing the READMEs improves the training-data problem on a years-long delay, but it improves the agents that read READMEs at runtime immediately.

The handbook just added a how-to for this: How to write install instructions for a Python library. It covers the README pattern that works for both audiences: lead with uv add, label pip install as the fallback, and cover extras, git installs, and CLI tools so a uv user never has to translate.

What you can do today

Three small changes, in order of how much they move the needle:

1. If you maintain a library, open the README and reorder the install section so uv add <pkg> appears first. The handbook’s install-instructions how-to has the full pattern.
2. If you have AI agents working on Python projects, drop in the interceptor pattern or one of the tool-specific config guides. It takes ten minutes and stops the next “the agent ran pip install in my project” surprise.
3. If you have one-off scripts paired with requirements.txt, convert them to PEP 723 inline metadata.