6e310f2702
This PR rewrites the resolver concept and adds a resolver internals page targeted at power users. The new resolution concept documentation has three parts: * An introduction for people how never heard of "resolution" before, and a motivating example what it does. I've also shoved the part about equally valid resolutions in there. * Features you commonly use: Non-universal vs. universal resolution, lowest resolution amd pre-releases. * Expert features, we don't advertise them, you'll only need them in complex cases when you already know and i kept them to the reference points you need in this case: Constraints, overrides and exclude-newer. I intentionally didn't lay out any detail of the resolution itself, the idea is that users get a vague sense of "uv has to select fitting versions", but then they learn the options they have to use and some common failure points without ever coming near SAT or even graphs. The resolution internals reference page is targeted at power users who need to understand what is going on behind the scenes. It assumes ample prior knowledge and exists to explain the uv-specific behaviors for someone who already understands dependency resolution conceptually and has interacted with their dependency tree before. I had a section on the lockfile but removed it because it found the lockfile to be too self-documenting. I haven't touched the readme. Closes #5603 Closes #5238 Closes #5237 --------- Co-authored-by: Zanie Blue <contact@zanie.dev>
5.4 KiB
uv
An extremely fast Python package and project manager, written in Rust.
Installing the Trio dependencies with a warm cache.
Highlights
- 🐍 Installs and manages Python versions.
- 🛠️ Runs and installs Python applications.
- ❇️ Runs scripts, with support for inline dependency metadata.
- 🗂️ Provides comprehensive project management, with a universal lockfile.
- 🏢 Supports Cargo-style workspaces for scalable projects.
- 🚀 A replacement for
pip,pip-tools,pipx,poetry,pyenv,virtualenv, and more. - ⚡️ 10-100x faster than
pipandpip-tools(pip-compileandpip-sync). - 💾 Disk-space efficient, with a global cache for dependency deduplication.
- ⏬ Installable without Rust or Python via
curlorpip. - 🖥️ Supports macOS, Linux, and Windows.
uv is backed by Astral, the creators of Ruff.
Getting started
Install uv with our official standalone installer:
$ curl -LsSf https://astral.sh/uv/install.sh | sh
$ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Then, check out the first steps or read on for a brief overview.
!!! tip
uv may also be installed with pip, Homebrew, and more. See all of the methods on the
[installation page](./installation.md).
Project management
uv manages project dependencies and environments:
$ uv init example
Initialized project `example` at `/home/user/example`
$ cd example
$ uv add ruff
Creating virtualenv at: .venv
Resolved 2 packages in 170ms
Built example @ file:///home/user/example
Prepared 2 packages in 627ms
Installed 2 packages in 1ms
+ example==0.1.0 (from file:///home/user/example)
+ ruff==0.5.4
$ uv run ruff check
All checks passed!
See the project guide to get started.
Tool management
uv executes and installs command-line tools provided by Python packages, similar to pipx.
Run a tool in an ephemeral environment with uvx:
$ uvx pycowsay 'hello world!'
Resolved 1 package in 167ms
Installed 1 package in 9ms
+ pycowsay==0.0.0.2
"""
------------
< hello world! >
------------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
Install a tool with uv tool install:
$ uv tool install ruff
Resolved 1 package in 6ms
Installed 1 package in 2ms
+ ruff==0.5.4
Installed 1 executable: ruff
$ ruff --version
ruff 0.5.4
See the tools guide to get started.
Python management
uv installs Python and allows quickly switching between versions.
Install multiple Python versions:
$ uv python install 3.10 3.11 3.12
Searching for Python versions matching: Python 3.10
Searching for Python versions matching: Python 3.11
Searching for Python versions matching: Python 3.12
Installed 3 versions in 3.42s
+ cpython-3.10.14-macos-aarch64-none
+ cpython-3.11.9-macos-aarch64-none
+ cpython-3.12.4-macos-aarch64-none
Download Python versions as needed:
$ uv venv --python 3.12.0
Using Python 3.12.0
Creating virtualenv at: .venv
Activate with: source .venv/bin/activate
$ uv run --python pypy@3.8 -- python --version
Python 3.8.16 (a9dbdca6fc3286b0addd2240f11d97d8e8de187a, Dec 29 2022, 11:45:30)
[PyPy 7.3.11 with GCC Apple LLVM 13.1.6 (clang-1316.0.21.2.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>>
Use a specific Python version in the current directory:
$ uv python pin pypy@3.11
Pinned `.python-version` to `pypy@3.11`
See the installing Python guide to get started.
The pip interface
uv provides a drop-in replacement for common pip, pip-tools, and virtualenv commands. uv
extends their interfaces with advanced features, such as dependency version overrides,
platform-independent resolutions, reproducible resolutions, alternative resolution strategies, and
more.
Compile requirements into a platform-independent requirements file:
$ uv pip compile docs/requirements.in \
--universal \
--output-file docs/requirements.txt
Resolved 43 packages in 12ms
Create a virtual environment:
$ uv venv
Using Python 3.12.3
Creating virtualenv at: .venv
Activate with: source .venv/bin/activate
Install the locked requirements:
$ uv pip sync docs/requirements.txt
Resolved 43 packages in 11ms
Installed 43 packages in 208ms
+ babel==2.15.0
+ black==24.4.2
+ certifi==2024.7.4
...
See the pip interface documentation to get started.
Next steps
See the first steps or jump straight to the guides to start using uv.