about things
1# uv
2
3uv isn't "faster pip." it's cargo for python - a unified toolchain that changes what's practical to do.
4
5## install
6
7```bash
8# macOS/Linux
9curl -LsSf https://astral.sh/uv/install.sh | sh
10
11# Windows
12powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
13```
14
15## the commands you actually use
16
17```bash
18uv sync # install deps from pyproject.toml
19uv run pytest # run in project environment
20uv add httpx # add a dependency
21uvx ruff check # run a tool without installing it
22```
23
24never use `uv pip`. that's the escape hatch, not the workflow.
25
26## zero-setup environments
27
28run tools without installing anything:
29
30```bash
31uvx flask --help
32uvx ruff check .
33uvx pytest
34```
35
36this creates an ephemeral environment, runs the tool, done. no virtualenv activation, no pip install.
37
38## the repro pattern
39
40testing specific versions without polluting your environment:
41
42```bash
43# test against a specific version
44uv run --with 'pydantic==2.11.4' repro.py
45
46# test a git branch before it's released
47uv run --with pydantic@git+https://github.com/pydantic/pydantic.git@fix-branch repro.py
48
49# combine: released package + unreleased fix
50uv run --with prefect==3.1.3 --with pydantic@git+https://github.com/pydantic/pydantic.git@fix repro.py
51```
52
53for monorepos with subdirectories:
54
55```bash
56uv run --with git+https://github.com/prefecthq/prefect.git@branch#subdirectory=src/integrations/prefect-redis repro.py
57```
58
59## inline script metadata
60
61PEP 723 lets you embed dependencies directly in a script:
62
63```python
64# /// script
65# dependencies = ["httpx", "rich"]
66# requires-python = ">=3.12"
67# ///
68
69import httpx
70from rich import print
71
72print(httpx.get("https://httpbin.org/get").json())
73```
74
75run with `uv run script.py` - uv reads the metadata and creates an environment with those dependencies. no pyproject.toml, no requirements.txt, just a self-contained script.
76
77this is how you share reproducible examples. put the dependencies in the file itself, and anyone with uv can run it.
78
79## shareable one-liners
80
81no file needed:
82
83```bash
84uv run --with 'httpx==0.27.0' python -c 'import httpx; print(httpx.get("https://httpbin.org/get").json())'
85```
86
87share in github issues, slack, anywhere. anyone with uv can run it.
88
89## stdin execution
90
91pipe code directly:
92
93```bash
94echo 'import sys; print(sys.version)' | uv run -
95pbpaste | uv run --with pandas -
96```
97
98## project workflow
99
100```bash
101uv init myproject # create new project
102cd myproject
103uv add httpx pydantic # add deps
104uv sync # install everything
105uv run python main.py # run in environment
106```
107
108`uv sync` reads `pyproject.toml` and `uv.lock`, installs exactly what's specified.
109
110## why this matters
111
112the old way:
1131. install python (which version?)
1142. create virtualenv
1153. activate it (did you remember?)
1164. pip install (hope versions resolve)
1175. run your code
118
119the uv way:
1201. `uv run your_code.py`
121
122uv handles python versions, environments, and dependencies implicitly. you stop thinking about environment management.
123
124sources:
125- [but really, what's so good about uv???](https://blog.zzstoatzz.io/but-really-whats-so-good-about-uv/)
126- [running list of repros via uv](https://blog.zzstoatzz.io/running-list-of-repros-via-uv/)