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.toml is like linking against libfoo >= 2.x; uv.lock is like shipping the exact .so versions from the box where it worked. Anyone who clones the repo and runs uv sync gets 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 and uv 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 Makefile with SUBDIRS = lib app that builds subprojects into one output tree, instead of cd lib && make install by 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 a bin/ (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/app with its own lib/ and an RPATH pointing at it, so it never loads the system’s copies.
  • activate is only a PATH convenience.
    • source .venv/bin/activate prepends .venv/bin to PATH, sets VIRTUAL_ENV, and changes the prompt. That is all it does.
    • It is never required. Running .venv/bin/python directly 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.toml has 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 own site-packages. The environment is baked into the launcher, so nothing ever needs activating.
    • Windows has no shebangs, so the launcher is a tiny .exe that does the same job: it knows which interpreter to start and which module to run.

What uv tool install does with them

  1. Creates one dedicated venv per tool, under uv’s tools directory (uv tool dir prints it — ~/.local/share/uv/tools/ on Linux, %APPDATA%\uv\tools\ on Windows).
  2. Installs the package and its whole dependency tree into that venv only.
  3. Links only the declared commands into a single bin directory on your PATH (uv tool dir --bin — ~/.local/bin on both). Nothing else from the venv is exposed.
  4. Writes a uv-receipt.toml in the tool’s venv recording what was requested, so uv tool upgrade can 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, then ln -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 foo deletes one directory and one link.
  • Not for libraries. A tool’s packages are invisible to your projects by design. If your code needs to import it, add it to the project with uv add instead.

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

TaskCommand
Install a CLI tooluv tool install <pkg>
Run a tool once without installing ituvx <pkg> (uv tool run)
List installed tools and their commandsuv tool list
Upgrade one / alluv tool upgrade <pkg> / uv tool upgrade --all
Removeuv tool uninstall <pkg>
Where the venvs / the launchers liveuv tool dir / uv tool dir --bin
Put the bin directory on PATH if it is missinguv tool update-shell

Day-to-day commands

TaskCommand
Create/refresh the environmentuv sync
Run inside the environmentuv run <cmd> (no activate needed)
Add a dependencyuv add <pkg> (edits pyproject.toml + lock)
Upgrade within rangesuv lock --upgrade
Inspect an installed packageuv 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.