uv, Lockfiles, and Workspaces
How modern Python projects manage dependencies with uv, what a workspace is, and how uv tool install gives you a global command without touching any project.
uv in one paragraph
uv replaces pip + venv + pip-tools with one fast tool. You declare what you want in pyproject.toml ("nvidia-nat[langchain]>=1.8.0,<1.9"), and uv sync creates .venv/ and installs everything. The C-world analogy: pyproject.toml is the configure.ac — the human-edited statement of requirements — and the environment is the build output. You never edit the environment by hand.
Lockfiles: the exact-versions manifest
uv sync also writes uv.lock: the exact resolved version of every package, direct and transitive, with checksums. The range in pyproject.toml says what’s acceptable; the lockfile says what was actually used.
- Analogy:
pyproject.tomlis like linking againstlibfoo >= 2.x;uv.lockis like shipping the exact.soversions from the box where it worked. Anyone who clones the repo and runsuv syncgets bit-for-bit the same environment. - Commit the lockfile. A repo without one can resolve different versions next month and break — “works on my machine” is usually a missing lockfile.
- Regenerating:
uv lock --upgrade(or edit the range anduv sync).
Workspaces: several packages, one environment
A Python project sometimes contains nested packages — e.g. a repo whose tooling scaffolds a subdirectory that is itself an installable package with its own pyproject.toml. A uv workspace ties them together:
# root pyproject.toml
[project]
dependencies = [
"some_subpackage", # depend on the nested package by name
]
[tool.uv.sources]
some_subpackage = { workspace = true } # ...and get it from this repo
[tool.uv.workspace]
members = ["some_subpackage"] # subdirectories that are packages
One uv sync at the root now installs the framework and the local package, editable, into a single shared .venv/, with one shared uv.lock. Change the subpackage source and the change is live immediately — no reinstall step.
Analogies:
- Make: a top-level
MakefilewithSUBDIRS = lib appthat builds subprojects into one output tree, instead ofcd lib && make installby hand. - Git submodules, inverted: a submodule pins someone else’s repo into yours; a workspace member is your own subdirectory promoted to a first-class package. Same repo, one history, one lock.
Without the workspace stanza, the nested package is invisible: uv sync installs only the root project’s dependencies, and imports from the subpackage fail even though the code is sitting right there.
Tools: a global command in an isolated environment
Everything above is about a project environment — a .venv/ that belongs to one repo. Sometimes you want the opposite: a Python program you use as a command, from any directory, that is not part of any project. That is uv tool install. A README will typically put it as “gives you a global foo command in its own isolated environment, with nothing to activate.” Each half of that sentence is one mechanism.
The three pieces underneath
- A virtual environment is just a directory.
- It holds its own interpreter (a symlink or copy), its own
site-packages/for libraries, and abin/(Scripts\on Windows). - Nothing in it is global. Two venvs can hold conflicting versions of the same library and never know about each other.
- Analogy: an application installed under
/opt/appwith its ownlib/and an RPATH pointing at it, so it never loads the system’s copies.
- It holds its own interpreter (a symlink or copy), its own
activateis only aPATHconvenience.source .venv/bin/activateprepends.venv/bintoPATH, setsVIRTUAL_ENV, and changes the prompt. That is all it does.- It is never required. Running
.venv/bin/pythondirectly gives exactly the same result, because the interpreter you run decides which libraries are visible, not any shell state.
- A package can declare commands.
pyproject.tomlhas a[project.scripts]table, e.g.foo = "foo.cli:main".- At install time the installer writes a small launcher script into the venv’s
bin/, whose shebang is that venv’s own interpreter:#!/path/to/venv/bin/python. - That shebang is the whole trick. The kernel reads
#!, execs that interpreter, and that interpreter can only see its ownsite-packages. The environment is baked into the launcher, so nothing ever needs activating. - Windows has no shebangs, so the launcher is a tiny
.exethat does the same job: it knows which interpreter to start and which module to run.
What uv tool install does with them
- Creates one dedicated venv per tool, under uv’s tools directory (
uv tool dirprints it —~/.local/share/uv/tools/on Linux,%APPDATA%\uv\tools\on Windows). - Installs the package and its whole dependency tree into that venv only.
- Links only the declared commands into a single bin directory on your
PATH(uv tool dir --bin—~/.local/binon both). Nothing else from the venv is exposed. - Writes a
uv-receipt.tomlin the tool’s venv recording what was requested, souv tool upgradecan rebuild it.
So “global” means the command is reachable from any shell, and “isolated” means its dependencies live where nothing else can see or break them.
- Analogy:
./configure --prefix=/opt/foo && make install, thenln -s /opt/foo/bin/foo /usr/local/bin/foo. uv does the prefix, the install and the symlink in one step, per tool. - It is the same idea as
pipx, which predates it.
Why it matters
- No dependency fights. A big CLI with a deep dependency tree, installed into a system or project Python, will eventually pin something that breaks something else. As a tool it cannot collide with anything.
- Clean removal.
uv tool uninstall foodeletes one directory and one link. - Not for libraries. A tool’s packages are invisible to your projects by design. If your code needs to
importit, add it to the project withuv addinstead.
Extras in install commands
uv tool install "foo[all]" — the bracketed part is an extra: a named group of optional dependencies the package declares under [project.optional-dependencies]. [all] conventionally pulls in every optional group. The quotes matter: an unquoted [...] is a glob pattern to the shell (zsh fails outright with “no matches found”).
Tool commands
| Task | Command |
|---|---|
| Install a CLI tool | uv tool install <pkg> |
| Run a tool once without installing it | uvx <pkg> (uv tool run) |
| List installed tools and their commands | uv tool list |
| Upgrade one / all | uv tool upgrade <pkg> / uv tool upgrade --all |
| Remove | uv tool uninstall <pkg> |
| Where the venvs / the launchers live | uv tool dir / uv tool dir --bin |
Put the bin directory on PATH if it is missing | uv tool update-shell |
Day-to-day commands
| Task | Command |
|---|---|
| Create/refresh the environment | uv sync |
| Run inside the environment | uv run <cmd> (no activate needed) |
| Add a dependency | uv add <pkg> (edits pyproject.toml + lock) |
| Upgrade within ranges | uv lock --upgrade |
| Inspect an installed package | uv pip show <pkg> |
uv run is the habit worth building: it guarantees the command executes in the project’s environment, like a wrapper script that sets PATH and LD_LIBRARY_PATH before exec’ing the real binary.