uv is a next-generation Python package and environment manager written in Rust, designed for speed, correctness, and interoperability. It unifies functionality traditionally spread across pip, virtualenv, poetry, pyenv, pipx, and twine—all while delivering 10–100× faster operations than pip on typical workloads.

Installation on Windows 11

For users with an existing Python installation, the recommended method uses the official installer script:

powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"

If execution policies block the script, first relax them for the current session:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Due to network restrictions in some regions, direct GitHub access may fail. In such cases, download the latest prebuilt binary manually:

• Navigate to GitHub Releases
• Download uv-x86_64-pc-windows-msvc.zip (e.g., version 0.11.1)
• Extract uv.exe, uvw.exe, and uvx.exe to a dedicated directory like C:\uv
• Add C:\uv to your system’s PATH environment variable

Verify installation:

uv --version

Project Initialization & Environment Setup

Create a new project scaffolded with modern defaults:

uv init myapp --python 3.13

This generates:

• pyproject.toml (with PEP 621 metadata)
• .gitignore, README.md, main.py
• .python-version (pinning Python 3.13)

Create and activate an isolated virtual environment:

uv venv --python 3.13 .venv
.venv\Scripts\activate

Unlike legacy tools, uv automatically respects .python-version and manages interpreter selection transparently.

Dependency Management

Modern workflows prioritize declarative dependency declarations in pyproject.toml. Use these commands instead of raw pip:

uv add requests pytest
uv remove pytest
uv sync  # installs exact versions from lockfile

To pin Python for the project:

uv python pin 3.12

This writes 3.12 to .python-version and ensures consistent interpreter resolution.

Cache Optimizaton

By default, uv stores cached packages and environments under %LOCALAPPDATA%\uv\Cache. To avoid hardlinking warnings (especially across drives), relocate it:

setx UV_CACHE_DIR "D:\uv-cache"

Then restart your terminal and confirm:

uv cache dir

Running Tools and Scripts

Execute scripts in the project environment without manual activation:

uv run python main.py
uv run pytest tests/
uv run black src/

Install and run CLI tools in ephemeral, isolated environments:

uvx ruff@0.6.0 check .
uvx black@24.4.0 --version

Tools installed via uvx are cached and reused, but never interfere with your project’s dependencies.

Configuration & Mirrors

Configure PyPI mirors inside pyproject.toml:

[[tool.uv.index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
default = true

Or override globally using environment variables or uv.toml.

Advanced Operations

Inspect dependency graphs:

uv tree --depth 2

Export locked dependenceis:

uv export --production > requirements.txt

Manage Python installations (if enabled):

uv python list
uv python install 3.12.5

Clear stale cache entries:

uv cache prune
uv cache clean

Integration Tips

In PyCharm or VS Code, point the Python interpreter to .venv\Scripts\python.exe. The IDE will auto-detect uv-managed environments when pyproject.toml is present.

For Playwright or other toolchains requiring binaries, use administrator privileges and set mirrors explicitly:

set PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright
uv add playwright
playwright install chromium