From dac696e9504002f76e950ec3836e9609c238ed40 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Tue, 23 Jul 2024 14:29:59 -0400 Subject: [PATCH] Bundle of documentation changes (#5307) Following #5239 --- docs/configuration/files.md | 4 +- docs/dependencies.md | 179 +++++++++++++----- docs/features.md | 24 +-- docs/guides/integration/commercial-indexes.md | 4 + docs/guides/integration/docker.md | 22 +-- docs/guides/integration/github.md | 20 +- docs/guides/integration/pre-commit.md | 6 +- docs/guides/projects.md | 4 +- docs/guides/scripts.md | 12 +- docs/index.md | 153 +++++++++++++-- docs/overview.md | 23 +++ docs/pip/compile.md | 12 +- docs/pip/dependencies.md | 6 +- docs/pip/environments.md | 4 +- docs/pip/packages.md | 2 +- docs/projects.md | 152 +++++++++++++-- docs/python.md | 0 docs/resolution.md | 6 +- docs/tools.md | 8 +- docs/workspaces.md | 4 +- mkdocs.template.yml | 3 +- 21 files changed, 495 insertions(+), 153 deletions(-) create mode 100644 docs/overview.md delete mode 100644 docs/python.md diff --git a/docs/configuration/files.md b/docs/configuration/files.md index 019049801584..0a46aa305173 100644 --- a/docs/configuration/files.md +++ b/docs/configuration/files.md @@ -8,7 +8,7 @@ in the nearest parent directory. If a `pyproject.toml` file is found, uv will read configuration from the `[tool.uv.pip]` table. For example, to set a persistent index URL, add the following to a `pyproject.toml`: -```toml +```toml title="project.toml" [tool.uv.pip] index-url = "https://test.pypi.org/simple" ``` @@ -18,7 +18,7 @@ the directory hierarchy.) If a `uv.toml` file is found, uv will read from the `[pip]` table. For example: -```toml +```toml title="uv.toml" [pip] index-url = "https://test.pypi.org/simple" ``` diff --git a/docs/dependencies.md b/docs/dependencies.md index 2bca8321bf70..8009ecdb27d2 100644 --- a/docs/dependencies.md +++ b/docs/dependencies.md @@ -19,7 +19,7 @@ standard. `project.dependencies` is structured as a list. Each entry includes a dependency name and version. An entry may include extras or environment markers for platform-specific packages. For example: -```toml +```toml title="pyproject.toml" [project] name = "albatross" version = "0.1.0" @@ -37,41 +37,126 @@ dependencies = [ ] ``` -If the project only requires packages from standaard package indexes, then `project.dependencies` is sufficient. If, the project depends on packages from Git, remote URLs, or local sources, `tool.uv.sources` is needed. +If the project only requires packages from standard package indexes, then `project.dependencies` is sufficient. If, the project depends on packages from Git, remote URLs, or local sources, `tool.uv.sources` is needed. ## Dependency sources -During development, the project may rely on a package that isn't available on PyPI. In the following example, the project will require several package sources: +During development, the project may rely on a package that isn't available on PyPI. The following additional sources are supported by uv: -- `tqdm` from a specific Git commit -- `importlib_metadata` from a dedicated URL -- `torch` from the PyTorch-specific index -- `mollymawk` from the current workspace +- Git +- URL +- Path +- Workspace -These requirements can be expressed by extending the definitions in the `project.dependencies` table with `tool.uv.sources` entries: +Only a single source may be defined for each dependency. + +Note that if a non-uv project uses a project with sources as a Git- or path-dependency, only +`project.dependencies` is respected, the information in the source table +will need to be re-specified in a format specific to the other package manager. + +### Git + +To add a Git dependency source, prefix a Git-compatible URL to clone with `git+`. -```toml +For example: + +```console +$ uv add git+https://github.com/encode/httpx +``` + +Will result in a `pyproject.toml` with: + +```toml title="pyproject.toml" +[project] +dependencies = [ + "httpx", +] + +[tool.uv.sources] +httpx = { git = "https://github.com/encode/httpx" } +``` + +A revision, tag, or branch may also be included, e.g.: + +```console +$ uv add git+https://github.com/encode/httpx --tag 0.27.0 +$ uv add git+https://github.com/encode/httpx --branch main +$ uv add git+https://github.com/encode/httpx --rev 326b943 +``` + +Git dependencies can also be manually added or edited in the `pyproject.toml` with the `{ git = }` syntax. A target revision may be specified with one of: `rev`, `tag`, or `branch`. A `subdirectory` may be specified if the package isn't in the repository root. + +### URL + +To add a URL source, provide a `https://` URL to either a wheel (ending in `.whl`) or a source distribution (ending in `.zip` or `.tar.gz`). + +For example: + +```console +$ uv add "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz" +``` + +Will result in a `pyproject.toml` with: + +```toml title="pyproject.toml" +[project] +dependencies = [ + "httpx", +] + +[tool.uv.sources] +httpx = { url = "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz" } +``` + +URL dependencies can also be manually added or edited in the `pyproject.toml` with the `{ url = }` syntax. A `subdirectory` may be specified if the if the source distribution isn't in the archive root. + +### Path + +To add a path source, provide the path of a wheel (ending in `.whl`), a source distribution (ending in `.zip` or `.tar.gz`), or a directory containing a `pyproject.toml`. + +For example: + +```console +$ uv add /example/foo.whl +``` + +Will result in a `pyproject.toml` with: + +```toml title="pyproject.toml" +[project] +dependencies = [ + "foo", +] + +[tool.uv.sources] +foo = { path = "/example/foo.whl" } +``` + +The path may also be a relative path, e.g.: + +```console +$ uv add ./foo +``` + +Note an [editable installation](#editables-dependencies) is not used for path dependencies. However, for directories, an editable installation may be requested, e.g.: + +```console +$ uv add --editable ./foo +``` + +However, it is recommended to use [_workspaces_](#workspaces) instead of manual path dependencies. + +### Workspace member + +To declare a workspace member, add the dependency with `{ workspace = true }`. All workspace members must be explicitly stated. Workspace members are [editable](#editables-dependencies) by default; `editable = false` may be included to install them as regular dependencies. See the [workspace](./workspaces.md) documentation for more details on workspaces. + +```toml title="pyproject.toml" [project] -name = "albatross" -version = "0.1.0" dependencies = [ - # Any version in this range. - "tqdm >=4.66.2,<5", - # Exactly this version of torch. - "torch ==2.2.2", - # Install transformers with the torch extra. - "transformers[torch] >=4.39.3,<5", - # Only install this package on Python versions prior to 3.10. - "importlib_metadata >=7.1.0,<8; python_version < '3.10'", "mollymawk ==0.1.0" ] [tool.uv.sources] -# Install a specific Git commit. -tqdm = { git = "https://github.com/tqdm/tqdm", rev = "cc372d09dcd5a5eabdc6ed4cf365bdb0be004d44" } -# Install a remote source distribution (`.zip`, `.tar.gz`) or wheel (`.whl`). -importlib_metadata = { url = "https://github.com/python/importlib_metadata/archive/refs/tags/v7.1.0.zip" } -# Use a package included in the same workspace (as an editable installation). mollymawk = { workspace = true } [tool.uv.workspace] @@ -80,22 +165,6 @@ include = [ ] ``` -uv supports the following sources: - -- **Git**: `git = `. A git-compatible URL to clone. A target revision may be specified with one of: `rev`, `tag`, or `branch`. A `subdirectory` may be specified if the package isn't in the repository root. -- **URL**: `url = `. An `https://` URL to either a wheel (ending in `.whl`) or a source distribution - (ending in `.zip` or `.tar.gz`). A `subdirectory` may be specified if the if the source distribution isn't in the archive root. -- **Path**: `path = `. A path to a wheel (ending in `.whl`), a source - distribution (ending in `.zip` or `.tar.gz`), or a directory containing a `pyproject.toml`. - The path may be absolute or relative path. It is recommended to use _workspaces_ instead of manual path dependencies. For directories, `editable = true` may be specified for an [editable](#editables-dependencies) installation. -- **Workspace**: `workspace = true`. All workspace dependencies must be explicitly stated. Workspace dependencies are [editable](#editables-dependencies) by default; `editable = false` may be specified to install them as regular dependencies. See the [workspace](./workspaces.md) documentation for more details on workspaces. - -Only a single source may be defined for each dependency. - -Note that if a non-uv project uses this project as a Git- or path-dependency, only -`project.dependencies` is respected, the information in the source table -will need to be specified in a format specific to the other package manager. - ## Optional dependencies It is common for projects that are published as libraries to make some features optional to reduce the default dependency tree. For example, @@ -107,7 +176,7 @@ from extra name to its dependencies, following [PEP 508](#pep-508) syntax. Optional dependencies can have entries in `tool.uv.sources` the same as normal dependencies. -```toml +```toml title="pyproject.toml" [project] name = "pandas" version = "1.0.0" @@ -126,19 +195,31 @@ excel = [ ] ``` +To add an optional dependency, use the `--optional ` option: + +```console +$ uv add httpx --optional network +``` + ## Development dependencies Unlike optional dependencies, development dependencies are local-only and will _not_ be included in the project requirements when published to PyPI or other indexes. As such, development dependencies are included under `[tool.uv]` instead of `[project]`. Development dependencies can have entries in `tool.uv.sources` the same as normal dependencies. -```toml +```toml title="pyproject.toml" [tool.uv] dev-dependencies = [ "pytest >=8.1.1,<9" ] ``` +To add a development dependency, include the `--dev` flag: + +```console +$ uv add ruff --dev` +``` + ## PEP 508 [PEP 508](https://peps.python.org/pep-0508/) defines a syntax for dependency specification. It is composed of, in order: @@ -182,4 +263,16 @@ There are some limitations to editables (mainly: the build backend needs to supp native modules aren't recompiled before import), but they are useful for development, as the virtual environment will always use the latest changes to the package. -uv uses editable installation for workspace packages and patched dependencies by default. +uv uses editable installation for workspace packages by default. + +To add an editable dependency, use the `--editable` flag: + +```console +$ uv add --editable ./path/foo +``` + +Or, to opt-out of using an editable dependency in a workspace: + +```console +$ uv add --no-editable ./path/foo +``` diff --git a/docs/features.md b/docs/features.md index ec105addd9a7..797a64aa3837 100644 --- a/docs/features.md +++ b/docs/features.md @@ -1,5 +1,5 @@ -# Feature overview +# Features uv supports the full Python development experience — from installing Python and hacking on simple scripts to working on large projects that support multiple Python versions and platforms. @@ -100,24 +100,4 @@ Managing and inspecting uv's state, such as the cache, storage directories, or p ## Next steps -Check out one of our guides to get started: - -- [Installing Python](./guides/install-python.md) -- [Running scripts](./guides/scripts.md) -- [Using tools](./guides/tools.md) -- [Working on projects](./guides/projects.md) -- [Using in Docker](./guides/integration/docker.md) -- [Using with pre-commit](./guides/integration/pre-commit.md) -- [Using in GitHub Actions](./guides/integration/github.md) -- [Using with commercial package indexes](./guides/integration/commercial-indexes.md) - -Or, explore the concept documentation for comprehensive breakdown of each feature: - -- [Projects](./projects.md) -- [Dependencies](./dependencies.md) -- [Workspaces](./workspaces.md) -- [Tools](./tools.md) -- [Python versions](./python-versions.md) -- [Resolution](./resolution.md) -- [Caching](./cache.md) -- [Authentication](./configuration/authentication.md) +Check out the [documentation overview](./overview.md) for a list of guides and concepts. diff --git a/docs/guides/integration/commercial-indexes.md b/docs/guides/integration/commercial-indexes.md index 665208e0369b..5fb8be544081 100644 --- a/docs/guides/integration/commercial-indexes.md +++ b/docs/guides/integration/commercial-indexes.md @@ -33,3 +33,7 @@ export UV_KEYRING_PROVIDER=subprocess # Configure the index URL with the username export UV_EXTRA_INDEX_URL=https://VssSessionToken@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/ ``` + +## Other indexes + +uv is also known to work with JFrog's Artifactory, the Google Cloud Artifact Registry, and AWS Code Artifact. diff --git a/docs/guides/integration/docker.md b/docs/guides/integration/docker.md index 18b6b6d7a2f3..4d60ff3089cf 100644 --- a/docs/guides/integration/docker.md +++ b/docs/guides/integration/docker.md @@ -12,14 +12,14 @@ docker run ghcr.io/astral-sh/uv --help uv can be installed by copying from the official Docker image: -```dockerfile +```dockerfile title="Dockerfile" FROM python:3.12-slim-bullseye COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv ``` Or with the standalone installer: -```dockerfile +```dockerfile title="Dockerfile" FROM python:3.12-slim-bullseye RUN apt-get update && apt-get install -y curl --no-install-recommends RUN curl -LsSf https://astral.sh/uv/install.sh | sh @@ -36,19 +36,19 @@ Once uv is installed in an image, it can be used to install some packages. The system Python environment is safe to use this context, since a container is already isolated. The `--system` flag can be used to install in the system environment: -```dockerfile +```dockerfile title="Dockerfile" RUN uv pip install --system ruff ``` To use the system Python environment by default, set the `UV_SYSTEM_PYTHON` variable: -```dockerfile +```dockerfile title="Dockerfile" ENV UV_SYSTEM_PYTHON=1 ``` Alternatively, a virtual environment can be created and activated: -```dockerfile +```dockerfile title="Dockerfile" RUN uv venv /opt/venv # Use the virtual environment automatically ENV VIRTUAL_ENV=/opt/venv @@ -58,7 +58,7 @@ ENV PATH="/opt/venv/bin:$PATH" When using a virtual environment, the `--system` flag should be omitted from uv invocations: -```dockerfile +```dockerfile title="Dockerfile" RUN uv pip install ruff ``` @@ -66,7 +66,7 @@ RUN uv pip install ruff To install requirements files, copy them into the container: -```dockerfile +```dockerfile title="Dockerfile" COPY requirements.txt . RUN uv pip install -r requirements.txt ``` @@ -75,7 +75,7 @@ RUN uv pip install -r requirements.txt When installing a project alongside requirements, it is prudent to separate copying the requirements from the rest of the source code. This allows the dependencies of the project (which do not change often) to be cached separately from the project itself (which changes very frequently). -```dockerfile +```dockerfile title="Dockerfile" COPY pyproject.toml . RUN uv pip install -r pyproject.toml COPY . . @@ -88,7 +88,7 @@ RUN uv pip install -e . If uv isn't needed in the final image, the binary can be mounted in each invocation: -```dockerfile +```dockerfile title="Dockerfile" RUN --mount=from=uv,source=/uv,target=/bin/uv \ uv pip install --system ruff ``` @@ -97,7 +97,7 @@ RUN --mount=from=uv,source=/uv,target=/bin/uv \ A [cache mount](https://docs.docker.com/build/guide/mounts/#add-a-cache-mount) can be used to improve performance across builds: -```dockerfile +```dockerfile title="Dockerfile" RUN --mount=type=cache,target=/root/.cache/uv \ ./uv pip install -r requirements.txt --> ``` @@ -105,7 +105,7 @@ RUN --mount=type=cache,target=/root/.cache/uv \ Note the cache directory's location can be determined with the `uv cache dir` command. Alternatively, the cache can be set to a constant location: -```dockerfile +```dockerfile title="Dockerfile" ENV UV_CACHE_DIR=/opt/uv-cache/ ``` diff --git a/docs/guides/integration/github.md b/docs/guides/integration/github.md index c0b2c49233d3..ac4d5961aa32 100644 --- a/docs/guides/integration/github.md +++ b/docs/guides/integration/github.md @@ -6,7 +6,7 @@ uv installation differs depending on the platform. ### on Unix -```yaml +```yaml title="example.yml" name: Example on Unix jobs: @@ -24,7 +24,7 @@ jobs: ### on Windows -```yaml +```yaml title="example.yml" name: Example on Windows jobs: @@ -43,7 +43,7 @@ jobs: ### Using a matrix -```yaml +```yaml title="example.yml" name: Example jobs: @@ -78,7 +78,7 @@ jobs: Python can be installed with the `python install` command: -```yaml +```yaml title="example.yml" steps: # ... setup up uv ... @@ -90,7 +90,7 @@ This will respect the Python version pinned in the project. Or, when using a matrix, as in: -```yaml +```yaml title="example.yml" strategy: matrix: python-version: @@ -101,7 +101,7 @@ strategy: Provide the version to the `python install` invocation: -```yaml +```yaml title="example.yml" steps: # ... setup up uv ... @@ -111,7 +111,7 @@ steps: Alternatively, the official GitHub `setup-python` action can be used. This is generally faster, but will not respect the project's pinned Python version. -```yaml +```yaml title="example.yml" steps: - name: "Set up Python" uses: actions/setup-python@v5 @@ -123,7 +123,7 @@ steps: Once uv and Python are installed, the project can be installed with `uv sync` and commands can be run in the environment with `uv run`: -```yaml +```yaml title="example.yml" steps: # ... setup up Python and uv ... @@ -139,7 +139,7 @@ steps: If using the `uv pip` interface instead of the uv project interface, uv requires a virtual environment by default. To allow installing packages into the system environment, use the `--system` flag on all `uv` invocations or set the `UV_SYSTEM_PYTHON` variable, e.g.: -```yaml +```yaml title="example.yml" steps: - name: Allow uv to use the system Python by default run: echo "UV_SYSTEM_PYTHON=1" >> $GITHUB_ENV @@ -147,7 +147,7 @@ steps: Now, `uv pip` can modify the system environment without creating and activating a virtual environment. -```yaml +```yaml title="example.yml" steps: # ... setup up Python and uv ... diff --git a/docs/guides/integration/pre-commit.md b/docs/guides/integration/pre-commit.md index 59463e9297d4..3ea63b900adb 100644 --- a/docs/guides/integration/pre-commit.md +++ b/docs/guides/integration/pre-commit.md @@ -4,7 +4,7 @@ An official pre-commit hook is provided at [`astral-sh/uv-pre-commit`](https://g To compile requirements via pre-commit, add the following to the `.pre-commit-config.yaml`: -```yaml +```yaml title=".pre-commit-config.yaml" - repo: https://github.com/astral-sh/uv-pre-commit # uv version. rev: 0.2.27 @@ -16,7 +16,7 @@ To compile requirements via pre-commit, add the following to the `.pre-commit-co To compile alternative files, modify `args` and `files`: -```yaml +```yaml title=".pre-commit-config.yaml" - repo: https://github.com/astral-sh/uv-pre-commit # uv version. rev: 0.2.27 @@ -29,7 +29,7 @@ To compile alternative files, modify `args` and `files`: To run the hook over multiple files at the same time: -```yaml +```yaml title=".pre-commit-config.yaml" - repo: https://github.com/astral-sh/uv-pre-commit # uv version. rev: 0.2.27 diff --git a/docs/guides/projects.md b/docs/guides/projects.md index c5b43a5b66fe..a4a198b73cba 100644 --- a/docs/guides/projects.md +++ b/docs/guides/projects.md @@ -21,7 +21,7 @@ $ uv init This will create the following directory structure: -``` +```text . ├── pyproject.toml ├── README.md @@ -52,7 +52,7 @@ run a project command. The `pyproject.toml` contains metadata about your project: -```toml +```toml title="pyproject.toml" [project] name = "hello-world" version = "0.1.0" diff --git a/docs/guides/scripts.md b/docs/guides/scripts.md index ed490b68084d..5cc9c8da587a 100644 --- a/docs/guides/scripts.md +++ b/docs/guides/scripts.md @@ -7,7 +7,7 @@ script dependencies are properly managed inside and outside of projects. If your script has no dependencies, you can execute it with `uv run`: -```python +```python title="example.py" print("Hello world") ``` @@ -33,7 +33,7 @@ $ uv run example.py Arguments may be provided to the script: -```python +```python title="example.py" import sys print(" ".join(sys.argv[1:])) @@ -63,7 +63,7 @@ of dependencies that are required for the script. Generally, it's recommended to For example, the following script requires `rich`. -```python +```python title="example.py" import time from rich.progress import track @@ -104,7 +104,7 @@ Python recently added a standard format for [inline script metadata](https://pac To use inline script metadata, include a `script` section at the top of the script: -```python +```python title="example.py" # /// script # dependencies = [ # "requests<3", @@ -140,7 +140,7 @@ $ uv run example.py uv also supports Python version requirements: -```python +```python title="example.py" # /// script # requires-python = ">=3.12" # dependencies = [] @@ -159,7 +159,7 @@ Note that when using inline script metadata, even if `uv run` is used in a _proj uv allows arbitrary Python versions to be requested on each script invocation, for example: -```python +```python title="example.py" import sys print(".".join(map(str, sys.version_info[:3]))) diff --git a/docs/index.md b/docs/index.md index 601d0e73aeba..fbf802adb36b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,7 @@ -An extremely fast Python version, package, and project manager, written in Rust. +An extremely fast Python package and project manager, written in Rust.

Shows a bar chart with benchmark results. @@ -24,27 +24,20 @@ An extremely fast Python version, package, and project manager, written in Rust. - 🐍 [Installs and manages](./guides/install-python.md) Python versions. - 🛠️ [Executes and installs](./guides/tools.md) commands provided by Python packages. -- ❇️ [Runs scripts](./guides/scripts.md) with inline dependency metadata. -- 🗂️ Provides comprehensive project management, with a multi-platform lock file. -- 🏢 Supports Cargo-style workspaces for large projects. -- 🚀 A replacement for `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, and more. +- ❇️ [Runs scripts](./guides/scripts.md) with [inline dependency metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata). +- 🗂️ Provides [comprehensive project management](./guides/projects.md), with a multi-platform lock file. +- 🏢 Supports Cargo-style [workspaces](./workspaces.md) for large projects. +- 🚀 A replacement for `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `virtualenv`, and more. - ⚡️ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip` and `pip-tools` (`pip-compile` and `pip-sync`). - 🧪 Tested at-scale against the top 10,000 PyPI packages. -- 💾 Disk-space efficient, with a global cache for dependency deduplication. +- 💾 Disk-space efficient, with a [global cache](./cache.md) for dependency deduplication. - ⁉️ Best-in-class error messages with a conflict-tracking resolver. - ⏬ A static binary that can be installed without Rust or Python via `curl` or `pip`. - 🖥️ Support for macOS, Linux, and Windows. uv is backed by [Astral](https://astral.sh), the creators of [Ruff](https://github.com/astral-sh/ruff). -## Replacement for `pip` and `pip-tools` - -uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands with support for -a wide range of advanced `pip` features, including editable installs, Git dependencies, direct URL dependencies, local dependencies, constraints, source distributions, HTML and JSON indexes, and more. - -uv extends these interfaces with advanced features, such as dependency version overrides, multi-platform resolutions, reproducible resolutions, alternative resolution strategies, and more. - ## Getting started Install uv with our official standalone installer: @@ -57,4 +50,136 @@ 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](./first-steps.md) or see more [installation methods](./installation.md). +Then, check out the [first steps](./first-steps.md), see more [installation methods](./installation.md), or read on for a brief overview. + +## Project management + +uv can manage project dependencies and environments: + +```console +$ 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](./guides/projects.md) to get started. + +## Tool management + +uv provides an interface for executing and installing command-line tools provided by Python packages, similar to `pipx`. + +Run a tool in an ephemeral environment with `uvx`: + +```console +$ 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`: + +```console +$ 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](./guides/tools.md) to get started. + +## Python management + +uv supports installing Python and managing multiple Python versions. + +Install the Python versions your project requires: + +```console +$ uv python install 3.10 3.11 3.12 +warning: `uv python install` is experimental and may change without warning +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 +``` + +Or, fetch Python versions on demand: + +```console +$ uv venv --python 3.12.0 +Creating virtualenv at: .venv +Activate with: source .venv/bin/activate +``` + +See the [installing Python guide](./guides/install-python.md) to get started. + +## Package management + +uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands with support for +a wide range of advanced `pip` features, including editable installs, Git dependencies, direct URL dependencies, local dependencies, constraints, source distributions, HTML and JSON indexes, and more. + +uv extends these interfaces with advanced features, such as dependency version overrides, multi-platform resolutions, reproducible resolutions, alternative resolution strategies, and more. + +Compile requirements into a multi-platform requirements file: + +```console +$ uv pip compile docs/requirements.in --universal --output-file docs/requirements.txt +Resolved 43 packages in 12ms +``` + +Create a virtual environment: + +```console +$ uv venv +Using Python 3.12.3 interpreter at: /opt/homebrew/opt/python@3.12/bin/python3.12 +Creating virtualenv at: .venv +Activate with: source .venv/bin/activate +``` + +Install the locked requirements: + +```console +$ 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 [uv pip documentation](./pip/environments.md) to get started. + +## Next steps + +See the [documentation overview](./overview.md) to learn more about uv. diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 000000000000..b0e5eeeef31f --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,23 @@ +# Overview + +Check out one of our guides to get started: + +- [Installing Python](./guides/install-python.md) +- [Running scripts](./guides/scripts.md) +- [Using tools](./guides/tools.md) +- [Working on projects](./guides/projects.md) +- [Using in Docker](./guides/integration/docker.md) +- [Using with pre-commit](./guides/integration/pre-commit.md) +- [Using in GitHub Actions](./guides/integration/github.md) +- [Using with commercial package indexes](./guides/integration/commercial-indexes.md) + +Or, explore the concept documentation for comprehensive breakdown of each feature: + +- [Projects](./projects.md) +- [Dependencies](./dependencies.md) +- [Workspaces](./workspaces.md) +- [Tools](./tools.md) +- [Python versions](./python-versions.md) +- [Resolution](./resolution.md) +- [Caching](./cache.md) +- [Authentication](./configuration/authentication.md) diff --git a/docs/pip/compile.md b/docs/pip/compile.md index 13eeece15899..75aa252b50eb 100644 --- a/docs/pip/compile.md +++ b/docs/pip/compile.md @@ -97,12 +97,11 @@ including a package in a constraints file will _not_ trigger the installation of To define an constraint, define a bound for a package: -```text -# constraints.txt +```text title="constraints.txt pydantic<2.0 ``` -To use a constraint file: +To use a constraints file: ```shell uv pip compile requirements.in --constraint constraints.txt @@ -122,15 +121,14 @@ Overrides are most often used to remove upper bounds from a transtive dependency To define an override, define the new requirement for the problematic package: -```text -# override.txt +```text overrides.txt c>=2.0 ``` -To use an override file: +To use an overrides file: ```shell -uv pip compile requirements.in --override override.txt +uv pip compile requirements.in --override overrides.txt ``` Now, resolution can succeed. However, note that if `a` is _correct_ that it does not support `c>=2.0` then a runtime error will likely be encountered when using the packages. diff --git a/docs/pip/dependencies.md b/docs/pip/dependencies.md index f090c36a2534..e703885099c4 100644 --- a/docs/pip/dependencies.md +++ b/docs/pip/dependencies.md @@ -8,7 +8,7 @@ The `pyproject.toml` file is the Python standard for defining configuration for To define project dependencies in a `pyproject.toml` file: -```toml +```toml title="pyproject.toml" [project] dependencies = [ "httpx", @@ -18,7 +18,7 @@ dependencies = [ To define optional dependencies in a `pyproject.toml` file: -```toml +```toml title="pyproject.toml" [project.optional-dependencies] cli = [ "rich", @@ -36,7 +36,7 @@ It is also common to use a lightweight `requirements.txt` format to declare the To define dependencies in a `requirements.in` file: -```text +```text title="requirements.in" httpx ruff>=0.3.0 ``` diff --git a/docs/pip/environments.md b/docs/pip/environments.md index 23227b132689..3d2cc870c2c9 100644 --- a/docs/pip/environments.md +++ b/docs/pip/environments.md @@ -26,8 +26,8 @@ uv venv --python 3.11 ``` Note this requires the requested Python version to be available on the system. -However, in preview mode, [uv will download Python for you](../python-versions.md). -See the [Python request](../python.md) documentation for more details on requesting Python versions. +However, if available, uv will download Python for you. +See the [Python version](../python-versions.md) documentation for more details. ## Using a virtual environment diff --git a/docs/pip/packages.md b/docs/pip/packages.md index a66d69c1106b..27a5dd73ec61 100644 --- a/docs/pip/packages.md +++ b/docs/pip/packages.md @@ -10,7 +10,7 @@ uv pip install flask To install a package with optional dependencies enabled, e.g., Flask with the "dotenv" extra: -``` +```bash uv pip install "flask[dotenv]" ``` diff --git a/docs/projects.md b/docs/projects.md index 310178470e65..811e9eafd3ca 100644 --- a/docs/projects.md +++ b/docs/projects.md @@ -1,55 +1,173 @@ # Projects +Python projects are help manage Python applications spanning multiple files. + +!!! note + + Looking for an introduction to creating a project with uv? See the [projects guide](./guides/projects.md) first. + ## Project metadata -`pyproject.toml` +Python project metadata is defined in a `pyproject.toml` file. +`uv init` can be used to create a new project, with a basic `pyproject.toml` and package definition. + +A minimal project definition includes a name, version, and description: + +```toml title="pyproject.toml" +[project] +name = "example" +version = "0.1.0" +description = "Add your description here" ``` -uv init + +Additionally, it's recommended to include a Python version requirement: + +```toml title="pyproject.toml" +[project] +requires-python = ">=3.12" ``` +This Python version requirement determines what syntax is valid in the project and affects the versions of dependencies which can be used (they must support the same Python range). + +The `pyproject.toml` also lists dependencies of the project. uv supports modifying the standard dependency list from the command line with `uv add` and `uv remove`. uv also supports [extended package sources](./dependencies.md) for advanced users. + +See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details on getting started with a `pyproject.toml`. + ## Project environments -`.venv` +uv creates a virtual environment in a `.venv` directory next to the `pyproject.toml`. This virtual environment contains the project and its dependencies. It is stored inside the project to make it easy for editors to find — they need the environment to give code completions and type hints. It is not recommended to include the `.venv` directory in version control, it should be excluded via a `.gitignore` entry (or similar). -``` -uv sync -``` +To run a command in the project environment, use `uv run`. Alternatively the project environment can be activated as normal for a virtual environment. -## Lock files +When `uv run` is invoked, it will create the project environment if it does not exist yet or ensure it is up to date if it exists. The project environment can also be explicitly created with `uv sync`. +It is _not_ recommended to modify the project environment manually, e.g., with `uv pip install`. For project dependencies, use `uv add` to add a package to the environment. For one-off requirements, use [`uvx`](./guides/tools.md) or [`uv run --with`](#running-commands-with-additional-dependencies). + +## Lock file + +uv creates a `uv.lock` file next to the `pyproject.toml`. + +`uv.lock` is a "universal" lockfile that contains exact information about your +project's dependencies. Unlike the `pyproject.toml` which is used to specify the +broad requirements of your project, the lockfile contains the exact resolved versions +that are installed in the project environment. This file should be checked into version +control, allowing for consistent and reproducible installations across machines. + +A "universal" lock file captures packages that would be installed across all possible Python markers such as operating system, architecture, and Python version. + +A lock file ensures that developers working on the project are using a consistent set of package versions. Additionally, it ensures when deploying the project as an application that the exact set of used package versions is known. + +The lock file is created and updated during uv invocations that use the project environment, i.e., `uv sync` and `uv run`. The lock file may also be explicitly updated using `uv lock`. + +`uv.lock` is a human-readable TOML file but is managed by uv and should not be +edited manually. There is no Python standard for lock files at this time, so the format of this file is specific to uv and not generally not usable by other tools. + +To avoid updating the lock file during `uv sync` and `uv run` invocations, use the `--frozen` flag. + +To assert the lock file is up to date, use the `--locked` flag. If the lock file is not up to date, an error will be raised instead of updating the lock file. + +## Managing dependencies + +uv is capable of adding, updating, and removing dependencies using the CLI. + +To add a dependency: + +```console +$ uv add httpx ``` -uv lock -``` -## Adding dependencies +uv supports adding [editable dependencies](./dependencies.md#editable-dependencies), [development dependencies](./dependencies.md#development-dependencies), [optional dependencies](./dependencies.md#optional-dependencies), and alternative [dependency sources](./dependencies.md#dependency-sources). See the [dependency specification](./dependencies.md) documentation for more details. + +uv will raise an error if the dependency cannot be resolved, e.g.: +```console +$ uv add 'httpx>9999' +error: Because only httpx<=9999 is available and example==0.1.0 depends on httpx>9999, we can conclude that example==0.1.0 cannot be used. +And because only example==0.1.0 is available and you require example, we can conclude that the requirements are unsatisfiable. ``` -uv add + +To remove a dependency: + +```console +$ uv remove httpx ``` -### Updating existing dependencies +To update an existing dependency, e.g., to add a lower bound to the `httpx` version: - +```console +$ uv add 'httpx>0.1.0' +``` -## Removing dependencies +Or, to change the bounds for `httpx`: +```console +$ uv add 'httpx<0.2.0' ``` -uv remove + +To add a dependency source, e.g., to use `httpx` from GitHub during development: + +```console +$ uv add git+https://github.com/encode/httpx ``` ## Running commands +When working on a project, it is installed into virtual environment at `.venv`. This environment is isolated from the current shell by default, so invocations that require the project, e.g., `python -c "import example"`, will fail. Instead, use `uv run` to run commands in the project environment: + +```console +$ uv run python -c "import example" ``` -uv run + +When using `run`, uv will ensure that the project environment is up to date before running the given command. + +The given command can be provided by the project environment or exist outside of it, e.g.: + +```console +# Presuming the project provides `example-cli` +$ uv run example-cli foo + +# Running a `bash` script that requires the project to be available +$ uv run bash scripts/foo.sh ``` ### Running commands with additional dependencies +Additional dependencies or different versions of dependencies can be requested per invocation. + +The `--with` option is used to include a dependency for the invocation, e.g., to request a different version of `httpx`: + +```console +$ uv run --with httpx==0.26.0 python -c "import httpx; print(httpx.__version__)" +0.26.0 +$ uv run --with httpx==0.25.0 python -c "import httpx; print(httpx.__version__)" +0.25.0 +``` + +The requested version will be respected regardless of the project's requirements. For example, even if the project requires `httpx==0.24.0`, the output above would be the same. + ### Running scripts Scripts that declare inline metadata are automatically executed in environments isolated from the project. See the [scripts guide](./guides/scripts.md#declaring-script-dependencies) for more details. +For example, given a script: + +```python title="example.py" +# /// script +# dependencies = [ +# "httpx", +# ] +# /// + +import httpx + +resp = httpx.get("https://peps.python.org/api/peps.json") +data = resp.json() +print([(k, v["title"]) for k, v in data.items()][:10]) +``` + +The invocation `uv run example.py` would run _isolated_ from the project with only the given dependencies listed. + ## Projects with many packages -See the [workspaces](./workspaces.md) documentation. +If working in a project composed of many packages, see the [workspaces](./workspaces.md) documentation. diff --git a/docs/python.md b/docs/python.md deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/docs/resolution.md b/docs/resolution.md index c615521253e0..2dae1e580f8f 100644 --- a/docs/resolution.md +++ b/docs/resolution.md @@ -16,13 +16,13 @@ without restricting the versions of transitive dependencies. For example, given the following `requirements.in` file: -```text +```text title="requirements.in" flask>=2.0.0 ``` Running `uv pip compile requirements.in` would produce the following `requirements.txt` file: -```text +```text title="requirements.txt" # This file was autogenerated by uv via the following command: # uv pip compile requirements.in blinker==1.7.0 @@ -44,7 +44,7 @@ werkzeug==3.0.1 However, `uv pip compile --resolution=lowest requirements.in` would instead produce: -```text +```text title="requirements.in" # This file was autogenerated by uv via the following command: # uv pip compile requirements.in --resolution=lowest click==7.1.2 diff --git a/docs/tools.md b/docs/tools.md index 68bd6123aadc..cddf9d870a03 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -30,25 +30,25 @@ Tool environments may be either mutated or re-created by subsequent `uv tool ins To upgrade a single package in a tool environment: -``` +```console $ uv tool install black --upgrade-package click ``` To upgrade all packages in a tool environment -``` +```console $ uv tool install black --upgrade ``` To reinstall a single package in a tool environment: -``` +```console $ uv tool install black --reinstall-package click ``` To reinstall all packages in a tool environment -``` +```console $ uv tool install black --reinstall ``` diff --git a/docs/workspaces.md b/docs/workspaces.md index 5559551df99a..faa95158856a 100644 --- a/docs/workspaces.md +++ b/docs/workspaces.md @@ -29,7 +29,7 @@ There a two main workspace structures: A **root package with helpers** and a **f The root workspace layout defines one main package in the root of the repository, with helper packages in `packages`. In this example `albatross/pyproject.toml` has both a `project` section and a `tool.uv.workspace` section. -``` +```text albatross ├── packages │ ├── provider_a @@ -56,7 +56,7 @@ In the flat layout, all packages are in the `packages` directory, and the root `pyproject.toml` defines a so-called virtual workspace. In this example `albatross/pyproject.toml` has only a `tool.uv.workspace` section, but no `project`. -``` +```text albatross ├── packages │ ├── albatross diff --git a/mkdocs.template.yml b/mkdocs.template.yml index 9ad05fe7b4d2..18c07c975ea5 100644 --- a/mkdocs.template.yml +++ b/mkdocs.template.yml @@ -72,7 +72,8 @@ nav: - Getting started: - Installation: installation.md - First steps: first-steps.md - - Feature overview: features.md + - Features: features.md + - Overview: overview.md - Guides: - Installing Python: guides/install-python.md - Running scripts: guides/scripts.md