uv-install-wheel

crates/uv-install-wheel/ is the low-level wheel installer. It owns the on-disk layout — where files go inside a venv, how RECORD is generated, how scripts get rewired — but does not orchestrate downloads, planning, or parallelism (those live in uv-installer).

The crate has been part of uv since the beginning; it was imported as install-wheel-rs in October 2023 (#34).

Purpose

Take a .whl file or an unpacked archive and place it correctly into a PythonEnvironment according to PEP 491 / PEP 427:

• Determine the install scheme (purelib / platlib / scripts / data / headers).
• Lay the files into the right directories using the requested LinkMode (clone / copy / hardlink / symlink).
• Rewrite shebangs in scripts.
• Compile the Windows console-script trampolines via uv-trampoline-builder.
• Validate and heal the RECORD file.

Key abstractions

• Layout — the resolved scheme paths for a target environment.
• LinkMode — how to place files: Clone, Copy, Hardlink, Symlink. Defaults adapt to filesystem capabilities.
• read_record / RecordEntry — parses the dist-info/RECORD file and validates entries.
• Error — install-time error type.

Recent security work

The Apr 2026 advisory GHSA-pjjw-68hj-v9mw fixed a bug where malformed RECORD entries could escape the venv on uninstall. The fix (#18942 / #18943) validates RECORD entries during install — paths must be relative and stay inside the venv — and heals known bad-but-safe variants.

See also

• uv-installer — the orchestrator above this crate.
• uv-virtualenv — the consumer that creates the venv.
• uv-trampoline-builder — Windows console-script support.