uv-virtualenv

crates/uv-virtualenv/ is a pure-Rust replacement for python -m venv. Unlike the standard library's venv module, it does not require running Python at creation time — uv inspects the base interpreter once (via uv-python) and writes out the venv layout directly.

Purpose

Create or remove a Python virtual environment quickly and consistently:

• Without spawning Python (which is slow on first run and can deadlock under heavy concurrency).
• Producing a venv that's compatible with the tools users expect (pip, python -m venv, IDEs).
• Across operating systems, with the right launcher shims (Windows trampolines, Unix shebangs).
• With activator scripts for every shell uv supports (bash, fish, csh, nushell, PowerShell, Windows cmd).

The crate's history goes back to October 2023 when it was imported as gourgeist (#62).

Directory layout

crates/uv-virtualenv/src/
├── lib.rs              # Public API: create + remove
├── virtualenv.rs       # 35k chars: the actual creation logic, paths, and metadata
├── _virtualenv.py      # site-customize.py-style script written into site-packages
└── activator/          # Per-shell activator templates
    ├── activate          # bash/zsh
    ├── activate.fish     # fish
    ├── activate.csh      # tcsh
    ├── activate.nu       # nushell
    ├── activate.bat      # Windows cmd
    └── activate.ps1      # PowerShell

Key abstractions

Type	File	Role
VirtualEnvironment	lib.rs (re-exports from virtualenv.rs)	A pointer to a created venv: root, scheme, python executable.
PyVenvConfiguration (re-exported from uv-python::virtualenv)	n/a	Models the pyvenv.cfg file.
Error	lib.rs	Creation/deletion failures.
remove_virtualenv	lib.rs	Recursively delete a venv directory.
create_venv (public function)	virtualenv.rs	Create the venv given a base Interpreter, target path, and prompt name.

How it works

create_venv does the following in order:

1. Compute paths. Use Interpreter::sysconfig to derive purelib, platlib, scripts, include, and data. The Posix vs. Windows scheme determines where things go.
2. Create directory structure. bin/ (Unix) or Scripts/ (Windows), lib/ and the site-packages tree.
3. Copy or symlink the Python interpreter into the venv's bin/. On Unix, hard-link or symlink to the base Python; on Windows, embed a small launcher (the trampoline binaries produced by uv-trampoline-builder).
4. Write pyvenv.cfg. The standard PEP 405 file describing the base prefix, which Python tools (including pip) use to recognize a venv.
5. Drop in _virtualenv.py. A small site-packages addition that mimics virtualenv's site customization for backwards compatibility.
6. Write activator scripts from the embedded templates, substituting the venv path and prompt.

Integration points

• uv-python provides the base Interpreter and is also used to re-discover the venv's Python after creation.
• uv-trampoline-builder provides the embedded Windows launcher binaries.
• uv venv (crates/uv/src/commands/venv.rs) is the user-facing wrapper. It also handles --clear semantics, prompt selection, and seeding (--seed installs pip, setuptools, wheel).
• uv-installer writes wheels into the venv after creation.

Entry points for modification

• Add support for a new shell activator — drop a template into activator/, register it in virtualenv.rs.
• Change the venv layout — virtualenv.rs is the single place that decides where files go. The Interpreter::sysconfig integration ensures uv-created venvs honor the same conventions as python -m venv.
• Add a launcher kind — Windows trampolines come from uv-trampoline-builder; Unix scripts are templates here.

Key source files

File	Purpose
crates/uv-virtualenv/src/virtualenv.rs	The 35k-character creation logic.
crates/uv-virtualenv/src/_virtualenv.py	The site-customization script copied into the venv.
crates/uv-virtualenv/src/activator/	Per-shell activator templates.

See also

• uv-python for the base interpreter discovery and querying.
• uv-trampoline-builder for Windows launchers.
• uv-installer for what populates the venv.