From ce2cd9a79d9ebdf50a24392b6b9cdea3e8fd0f04 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Tue, 30 Jul 2024 17:16:35 -0500 Subject: [PATCH] Wrap documentation at 100 characters --- CONTRIBUTING.md | 56 ++++-- STYLE.md | 16 +- docs/concepts/cache.md | 63 +++--- docs/concepts/dependencies.md | 99 ++++++---- docs/concepts/projects.md | 65 +++++-- docs/concepts/python-versions.md | 52 +++-- docs/concepts/resolution.md | 97 +++++----- docs/concepts/tools.md | 47 +++-- docs/concepts/workspaces.md | 28 +-- docs/configuration/authentication.md | 38 ++-- docs/configuration/environment.md | 51 ++--- docs/configuration/files.md | 8 +- docs/configuration/index.md | 3 +- docs/features.md | 15 +- docs/first-steps.md | 12 +- docs/guides/index.md | 3 +- docs/guides/install-python.md | 30 ++- .../guides/integration/alternative-indexes.md | 35 +++- docs/guides/integration/docker.md | 13 +- docs/guides/integration/github.md | 13 +- docs/guides/integration/pre-commit.md | 3 +- docs/guides/projects.md | 65 +++---- docs/guides/scripts.md | 37 ++-- docs/guides/tools.md | 28 ++- docs/index.md | 28 ++- docs/installation.md | 17 +- docs/pip/compatibility.md | 180 +++++++++--------- docs/pip/compile.md | 51 +++-- docs/pip/dependencies.md | 17 +- docs/pip/environments.md | 94 +++++---- docs/pip/index.md | 10 +- docs/pip/inspection.md | 3 +- docs/pip/packages.md | 6 +- docs/platforms.md | 21 +- 34 files changed, 795 insertions(+), 509 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d807e0225e45..e19cdde4d59a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,10 @@ # Contributing -We have issues labeled as [Good First Issue](https://github.com/astral-sh/uv/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) and [Help Wanted](https://github.com/astral-sh/uv/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) which are good opportunities for new contributors. +We have issues labeled as [Good First +Issue](https://github.com/astral-sh/uv/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) +and [Help +Wanted](https://github.com/astral-sh/uv/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) +which are good opportunities for new contributors. ## Setup @@ -26,7 +30,8 @@ See the [Python](#python) section for instructions on installing the Python vers ### Windows -You can install CMake from the [installers](https://cmake.org/download/) or with `pipx install cmake`. +You can install CMake from the [installers](https://cmake.org/download/) or with `pipx install +cmake`. ## Testing @@ -55,10 +60,11 @@ cargo run -- pip install requests ### Testing on Windows -When testing debug builds on Windows, the stack can overflow resulting in a `STATUS_STACK_OVERFLOW` error code. -This is due to a small stack size limit on Windows that we encounter when running unoptimized builds — the release -builds do not have this problem. We [added a `UV_STACK_SIZE` variable](https://github.com/astral-sh/uv/pull/941) to -bypass this problem during testing. We recommend bumping the stack size from the default of 1MB to 2MB, for example: +When testing debug builds on Windows, the stack can overflow resulting in a `STATUS_STACK_OVERFLOW` +error code. This is due to a small stack size limit on Windows that we encounter when running +unoptimized builds — the release builds do not have this problem. We [added a `UV_STACK_SIZE` +variable](https://github.com/astral-sh/uv/pull/941) to bypass this problem during testing. We +recommend bumping the stack size from the default of 1MB to 2MB, for example: ```powershell $Env:UV_STACK_SIZE = '2000000' @@ -66,7 +72,11 @@ $Env:UV_STACK_SIZE = '2000000' ## Running inside a Docker container -Source distributions can run arbitrary code on build and can make unwanted modifications to your system (["Someone's Been Messing With My Subnormals!" on Blogspot](https://moyix.blogspot.com/2022/09/someones-been-messing-with-my-subnormals.html), ["nvidia-pyindex" on PyPI](https://pypi.org/project/nvidia-pyindex/)), which can even occur when just resolving requirements. To prevent this, there's a Docker container you can run commands in: +Source distributions can run arbitrary code on build and can make unwanted modifications to your +system (["Someone's Been Messing With My Subnormals!" on +Blogspot](https://moyix.blogspot.com/2022/09/someones-been-messing-with-my-subnormals.html), +["nvidia-pyindex" on PyPI](https://pypi.org/project/nvidia-pyindex/)), which can even occur when +just resolving requirements. To prevent this, there's a Docker container you can run commands in: ```bash docker buildx build -t uv-builder -f builder.dockerfile --load . @@ -75,15 +85,20 @@ cargo build --target x86_64-unknown-linux-musl --profile profiling docker run --rm -it -v $(pwd):/app uv-builder /app/target/x86_64-unknown-linux-musl/profiling/uv-dev resolve-many --cache-dir /app/cache-docker /app/scripts/popular_packages/pypi_10k_most_dependents.txt ``` -We recommend using this container if you don't trust the dependency tree of the package(s) you are trying to resolve or install. +We recommend using this container if you don't trust the dependency tree of the package(s) you are +trying to resolve or install. ## Profiling and Benchmarking -Please refer to Ruff's [Profiling Guide](https://github.com/astral-sh/ruff/blob/main/CONTRIBUTING.md#profiling-projects), it applies to uv, too. +Please refer to Ruff's [Profiling +Guide](https://github.com/astral-sh/ruff/blob/main/CONTRIBUTING.md#profiling-projects), it applies +to uv, too. -We provide diverse sets of requirements for testing and benchmarking the resolver in `scripts/requirements` and for the installer in `scripts/requirements/compiled`. +We provide diverse sets of requirements for testing and benchmarking the resolver in +`scripts/requirements` and for the installer in `scripts/requirements/compiled`. -You can use `scripts/benchmark` to benchmark predefined workloads between uv versions and with other tools, e.g., from the `scripts/benchmark` directory: +You can use `scripts/benchmark` to benchmark predefined workloads between uv versions and with other +tools, e.g., from the `scripts/benchmark` directory: ```shell uv run resolver \ @@ -96,7 +111,9 @@ uv run resolver \ ### Analyzing concurrency -You can use [tracing-durations-export](https://github.com/konstin/tracing-durations-export) to visualize parallel requests and find any spots where uv is CPU-bound. Example usage, with `uv` and `uv-dev` respectively: +You can use [tracing-durations-export](https://github.com/konstin/tracing-durations-export) to +visualize parallel requests and find any spots where uv is CPU-bound. Example usage, with `uv` and +`uv-dev` respectively: ```shell RUST_LOG=uv=info TRACING_DURATIONS_FILE=target/traces/jupyter.ndjson cargo run --features tracing-durations-export --profile profiling -- pip compile scripts/requirements/jupyter.in @@ -157,15 +174,17 @@ To preview any changes to the documentation locally: The documentation should then be available locally at [http://127.0.0.1:8000/uv/](http://127.0.0.1:8000/uv/). -To update the documentation dependencies, edit `docs/requirements.in` and `docs/requirements-insiders.in`, then run: +To update the documentation dependencies, edit `docs/requirements.in` and +`docs/requirements-insiders.in`, then run: ```shell uv pip compile docs/requirements.in -o docs/requirements.txt --universal -p 3.12 uv pip compile docs/requirements-insiders.in -o docs/requirements-insiders.txt --universal -p 3.12 ``` -Documentation is deployed automatically on release by publishing to the [Astral documentation](https://github.com/astral-sh/docs) -repository, which itself deploys via Cloudflare Pages. +Documentation is deployed automatically on release by publishing to the [Astral +documentation](https://github.com/astral-sh/docs) repository, which itself deploys via Cloudflare +Pages. ## Releases @@ -183,6 +202,7 @@ Then, open a pull request e.g. `Bump version to ...`. Binary builds will automatically be tested for the release. -After merging the pull request, run the [release workflow](https://github.com/astral-sh/uv/actions/workflows/release.yml) -with the version tag. **Do not include a leading `v`**. -The release will automatically be created on GitHub after everything else publishes. +After merging the pull request, run the [release +workflow](https://github.com/astral-sh/uv/actions/workflows/release.yml) with the version tag. **Do +not include a leading `v`**. The release will automatically be created on GitHub after everything +else publishes. diff --git a/STYLE.md b/STYLE.md index 0d68a4e777d1..12ee63719050 100644 --- a/STYLE.md +++ b/STYLE.md @@ -1,6 +1,7 @@ # Style guide -_The following is a work-in-progress style guide for our user-facing messaging in the CLI output and documentation_. +_The following is a work-in-progress style guide for our user-facing messaging in the CLI output and +documentation_. ## General @@ -9,9 +10,12 @@ _The following is a work-in-progress style guide for our user-facing messaging i 1. Always wrap em-dashes in spaces, e.g., "hello — world" not "hello—world". 1. Hyphenate compound words, e.g., use "platform-specific" not "platform specific". 1. Use backticks to escape: commands, code expressions, package names, and file paths. -1. Use less than and greater than symbols to wrap bare URLs, e.g., `` (unless it is an example; then, use backticks). +1. Use less than and greater than symbols to wrap bare URLs, e.g., `` (unless it + is an example; then, use backticks). 1. Avoid bare URLs outside of reference documentation, prefer labels, e.g., `[name](url)`. -1. If a message ends with a single relevant value, precede it with a colon, e.g., `This is the value: value`. If the value is a literal, wrap it in backticks. +1. If a message ends with a single relevant value, precede it with a colon, e.g., `This is the + value: value`. If the value is a literal, wrap it in backticks. +1. Markdown files should be wrapped at 100 characters ## Styling uv @@ -82,12 +86,14 @@ The documentation is divided into: ## CLI -1. Do not use periods at the end of sentences :), unless the message spans more than a single sentence. +1. Do not use periods at the end of sentences :), unless the message spans more than a single + sentence. 1. May use the second-person point of view, e.g., "Did you mean...?". ### Colors and style -1. All CLI output must be interpretable and understandable _without_ the use of color and other styling. (For example: even if a command is rendered in green, wrap it in backticks.) +1. All CLI output must be interpretable and understandable _without_ the use of color and other + styling. (For example: even if a command is rendered in green, wrap it in backticks.) 1. `NO_COLOR` must be respected when using any colors or styling. 1. `UV_NO_PROGRESS` must be respected when using progress-styling like bars or spinners. 1. In general, use: diff --git a/docs/concepts/cache.md b/docs/concepts/cache.md index 4188977321db..05afa4319e83 100644 --- a/docs/concepts/cache.md +++ b/docs/concepts/cache.md @@ -2,33 +2,34 @@ ## Dependency caching -uv uses aggressive caching to avoid re-downloading (and re-building dependencies) that have -already been accessed in prior runs. +uv uses aggressive caching to avoid re-downloading (and re-building dependencies) that have already +been accessed in prior runs. The specifics of uv's caching semantics vary based on the nature of the dependency: - **For registry dependencies** (like those downloaded from PyPI), uv respects HTTP caching headers. -- **For direct URL dependencies**, uv respects HTTP caching headers, and also caches based on - the URL itself. -- **For Git dependencies**, uv caches based on the fully-resolved Git commit hash. As such, - `uv pip compile` will pin Git dependencies to a specific commit hash when writing the resolved - dependency set. +- **For direct URL dependencies**, uv respects HTTP caching headers, and also caches based on the + URL itself. +- **For Git dependencies**, uv caches based on the fully-resolved Git commit hash. As such, `uv pip + compile` will pin Git dependencies to a specific commit hash when writing the resolved dependency + set. - **For local dependencies**, uv caches based on the last-modified time of the source archive (i.e., the local `.whl` or `.tar.gz` file). For directories, uv caches based on the last-modified time of the `pyproject.toml`, `setup.py`, or `setup.cfg` file. -It's safe to run multiple uv commands concurrently, even against the same virtual environment. -uv's cache is designed to be thread-safe and append-only, and thus robust to multiple concurrent -readers and writers. uv applies a file-based lock to the target virtual environment when installing, -to avoid concurrent modifications across processes. +It's safe to run multiple uv commands concurrently, even against the same virtual environment. uv's +cache is designed to be thread-safe and append-only, and thus robust to multiple concurrent readers +and writers. uv applies a file-based lock to the target virtual environment when installing, to +avoid concurrent modifications across processes. -Note that it's _not_ safe to modify the uv cache (e.g., `uv cache clean`) while other uv commands are -running, and _never_ safe to modify the cache directly (e.g., by removing a file or directory). +Note that it's _not_ safe to modify the uv cache (e.g., `uv cache clean`) while other uv commands +are running, and _never_ safe to modify the cache directly (e.g., by removing a file or directory). If you're running into caching issues, uv includes a few escape hatches: - To force uv to revalidate cached data for all dependencies, run `uv pip install --refresh ...`. -- To force uv to revalidate cached data for a specific dependency, run, e.g., `uv pip install --refresh-package flask ...`. +- To force uv to revalidate cached data for a specific dependency, run, e.g., `uv pip install + --refresh-package flask ...`. - To force uv to ignore existing installed versions, run `uv pip install --reinstall ...`. ## Clearing the cache @@ -36,25 +37,27 @@ If you're running into caching issues, uv includes a few escape hatches: uv provides a few different mechanisms for removing entries from the cache: - `uv cache clean` removes _all_ cache entries from the cache directory, clearing it out entirely. -- `uv cache clean ruff` removes all cache entries for the `ruff` package, useful for invalidating the cache for a - single or finite set of packages. -- `uv cache prune` removes all _unused_ cache entries. For example, the cache directory may contain entries created in - previous uv versions that are no longer necessary and can be safely removed. `uv cache prune` is safe to - run periodically, to keep the cache directory clean. +- `uv cache clean ruff` removes all cache entries for the `ruff` package, useful for invalidating + the cache for a single or finite set of packages. +- `uv cache prune` removes all _unused_ cache entries. For example, the cache directory may contain + entries created in previous uv versions that are no longer necessary and can be safely removed. + `uv cache prune` is safe to run periodically, to keep the cache directory clean. ## Caching in continuous integration -It's common to cache package installation artifacts in continuous integration environments (like GitHub Actions or -GitLab CI) to speed up subsequent runs. +It's common to cache package installation artifacts in continuous integration environments (like +GitHub Actions or GitLab CI) to speed up subsequent runs. -By default, uv caches both the wheels that it builds from source and the pre-built wheels that it downloads directly, -to enable high-performance package installation. +By default, uv caches both the wheels that it builds from source and the pre-built wheels that it +downloads directly, to enable high-performance package installation. -However, in continuous integration environments, persisting pre-built wheels may be undesirable. With uv, it turns out -that it's often faster to _omit_ pre-built wheels from the cache (and instead re-download them from the registry on each -run). On the other hand, caching wheels that are built from source tends to be worthwhile, since the wheel building -process can be expensive, especially for extension modules. +However, in continuous integration environments, persisting pre-built wheels may be undesirable. +With uv, it turns out that it's often faster to _omit_ pre-built wheels from the cache (and instead +re-download them from the registry on each run). On the other hand, caching wheels that are built +from source tends to be worthwhile, since the wheel building process can be expensive, especially +for extension modules. -To support this caching strategy, uv provides a `uv cache prune --ci` command, which removes all pre-built wheels from -the cache but retains any wheels that were built from source. We recommend running `uv cache prune --ci` at the end of -your continuous integration job to ensure maximum cache efficiency. +To support this caching strategy, uv provides a `uv cache prune --ci` command, which removes all +pre-built wheels from the cache but retains any wheels that were built from source. We recommend +running `uv cache prune --ci` at the end of your continuous integration job to ensure maximum cache +efficiency. diff --git a/docs/concepts/dependencies.md b/docs/concepts/dependencies.md index 8009ecdb27d2..efeb686f8bc2 100644 --- a/docs/concepts/dependencies.md +++ b/docs/concepts/dependencies.md @@ -1,23 +1,26 @@ # Specifying dependencies -In uv, project dependency specification is divided between two `pyproject.toml` tables: `project.dependencies` and -`tool.uv.sources`. +In uv, project dependency specification is divided between two `pyproject.toml` tables: +`project.dependencies` and `tool.uv.sources`. -`project.dependencies` is used to define the standards-compliant dependency metadata, -propagated when uploading to PyPI or building a wheel. `tool.uv.sources` is used to specify the _sources_ +`project.dependencies` is used to define the standards-compliant dependency metadata, propagated +when uploading to PyPI or building a wheel. `tool.uv.sources` is used to specify the _sources_ required to install the dependencies, which can come from a Git repository, a URL, a local path, a -different index, etc. This metadata must be expressed separately because the `project.dependencies` standard does not allow these common patterns. +different index, etc. This metadata must be expressed separately because the `project.dependencies` +standard does not allow these common patterns. ## Project dependencies The `project.dependencies` table represents the dependencies that are used when uploading to PyPI or -building a wheel. Individual dependencies are specified using [PEP 508](#pep-508) syntax, and the table follows the [PEP 621](https://packaging.python.org/en/latest/specifications/pyproject-toml/) +building a wheel. Individual dependencies are specified using [PEP 508](#pep-508) syntax, and the +table follows the [PEP 621](https://packaging.python.org/en/latest/specifications/pyproject-toml/) standard. -`project.dependencies` defines the packages that are required for the project, along with the version constraints that should be used when installing them. +`project.dependencies` defines the packages that are required for the project, along with the +version constraints that should be used when installing them. -`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: +`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 title="pyproject.toml" [project] @@ -37,11 +40,14 @@ dependencies = [ ] ``` -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. +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. The following additional sources are supported by uv: +During development, the project may rely on a package that isn't available on PyPI. The following +additional sources are supported by uv: - Git - URL @@ -51,8 +57,8 @@ During development, the project may rely on a package that isn't available on Py 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. +`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 @@ -84,11 +90,14 @@ $ 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. +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`). +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: @@ -108,11 +117,14 @@ dependencies = [ 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. +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`. +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: @@ -138,7 +150,8 @@ The path may also be a relative path, e.g.: $ 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.: +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 @@ -148,7 +161,10 @@ However, it is recommended to use [_workspaces_](#workspaces) instead of manual ### 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. +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] @@ -167,9 +183,12 @@ include = [ ## 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, -Pandas has an [`excel` extra](https://pandas.pydata.org/docs/getting_started/install.html#excel-files) -and a [`plot` extra](https://pandas.pydata.org/docs/getting_started/install.html#visualization) to avoid installation of Excel parsers and `matplotlib` unless someone explicitly requires them. Extras are requested with the `package[]` syntax, e.g., `pandas[plot, excel]`. +It is common for projects that are published as libraries to make some features optional to reduce +the default dependency tree. For example, Pandas has an [`excel` +extra](https://pandas.pydata.org/docs/getting_started/install.html#excel-files) and a [`plot` +extra](https://pandas.pydata.org/docs/getting_started/install.html#visualization) to avoid +installation of Excel parsers and `matplotlib` unless someone explicitly requires them. Extras are +requested with the `package[]` syntax, e.g., `pandas[plot, excel]`. Optional dependencies are specified in `[project.optional-dependencies]`, a TOML table that maps from extra name to its dependencies, following [PEP 508](#pep-508) syntax. @@ -203,7 +222,9 @@ $ 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]`. +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. @@ -222,7 +243,8 @@ $ 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: +[PEP 508](https://peps.python.org/pep-0508/) defines a syntax for dependency specification. It is +composed of, in order: - The dependency name - The extras you want (optional) @@ -238,30 +260,31 @@ A star can be used for the last digit with equals, e.g. `foo ==2.1.*` will accep the 2.1 series. Similarly, `~=` matches where the last digit is equal or higher, e.g., `foo ~=1.2` is equal to `foo >=1.2,<2`, and `foo ~=1.2.3` is equal to `foo >=1.2.3,<1.3`. -Extras are comma-separated in square bracket between name and version, e.g., `pandas[excel,plot] ==2.2`. Whitespace between extra names is ignored. +Extras are comma-separated in square bracket between name and version, e.g., `pandas[excel,plot] +==2.2`. Whitespace between extra names is ignored. Some dependencies are only required in specific environments, e.g., a specific Python version or operating system. For example to install the `importlib-metadata` backport for the -`importlib.metadata` module, use `importlib-metadata >=7.1.0,<8; python_version < '3.10'`. -To install `colorama` on Windows (but omit it on other platforms), use -`colorama >=0.4.6,<5; platform_system == "Windows"`. +`importlib.metadata` module, use `importlib-metadata >=7.1.0,<8; python_version < '3.10'`. To +install `colorama` on Windows (but omit it on other platforms), use `colorama >=0.4.6,<5; +platform_system == "Windows"`. -Markers are combined with `and`, `or`, and parentheses, e.g., `aiohttp >=3.7.4,<4; (sys_platform != 'win32' or implementation_name != 'pypy') and python_version >= '3.10'`. -Note that versions within markers must be quoted, while versions _outside_ of markers must _not_ be -quoted. +Markers are combined with `and`, `or`, and parentheses, e.g., `aiohttp >=3.7.4,<4; (sys_platform != +'win32' or implementation_name != 'pypy') and python_version >= '3.10'`. Note that versions within +markers must be quoted, while versions _outside_ of markers must _not_ be quoted. ## Editable dependencies A regular installation of a directory with a Python package first builds a wheel and then installs -that wheel into your virtual environment, copying all source files. When the package source files are edited, -the virtual environment will contain outdated versions. +that wheel into your virtual environment, copying all source files. When the package source files +are edited, the virtual environment will contain outdated versions. -Editable installations solve this problem by adding a link to the project within the virtual environment -(a `.pth` file), which instructs the interpreter to include the source files directly. +Editable installations solve this problem by adding a link to the project within the virtual +environment (a `.pth` file), which instructs the interpreter to include the source files directly. -There are some limitations to editables (mainly: the build backend needs to support them, and -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. +There are some limitations to editables (mainly: the build backend needs to support them, and 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 by default. diff --git a/docs/concepts/projects.md b/docs/concepts/projects.md index 47257fc78f5e..4303fa6b0902 100644 --- a/docs/concepts/projects.md +++ b/docs/concepts/projects.md @@ -28,9 +28,12 @@ Additionally, it's recommended to include a Python version requirement: 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). +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. +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. !!! tip @@ -38,13 +41,23 @@ The `pyproject.toml` also lists dependencies of the project. uv supports modifyi ## Project environments -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 is automatically excluded from `git` with an internal `.gitignore` file. +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 is automatically excluded +from `git` with an internal `.gitignore` file. -To run a command in the project environment, use `uv run`. Alternatively the project environment can be activated as normal for a virtual environment. +To run a command in the project environment, use `uv run`. Alternatively the project environment can +be activated as normal for a virtual environment. -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`. +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). +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). ## Lockfile @@ -62,14 +75,17 @@ A lockfile ensures that developers working on the project are using a consistent versions. Additionally, it ensures when deploying the project as an application that the exact set of used package versions is known. -The lockfile is created and updated during uv invocations that use the project environment, i.e., `uv sync` and `uv run`. The lockfile may also be explicitly updated using `uv lock`. +The lockfile is created and updated during uv invocations that use the project environment, i.e., +`uv sync` and `uv run`. The lockfile 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 lockfiles at this time, so the format of this file is specific to uv and not generally not usable by other tools. +`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 lockfiles 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 lockfile during `uv sync` and `uv run` invocations, use the `--frozen` flag. -To assert the lockfile is up to date, use the `--locked` flag. If the lockfile is not up to date, an error will be raised instead of updating the lockfile. +To assert the lockfile is up to date, use the `--locked` flag. If the lockfile is not up to date, an +error will be raised instead of updating the lockfile. ## Managing dependencies @@ -81,7 +97,11 @@ To add a dependency: $ uv add httpx ``` -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 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.: @@ -117,13 +137,16 @@ $ 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: +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" ``` -When using `run`, uv will ensure that the project environment is up to date before running the given command. +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.: @@ -139,7 +162,8 @@ $ uv run bash scripts/foo.sh 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`: +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__)" @@ -148,11 +172,14 @@ $ 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. +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. +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: @@ -170,8 +197,10 @@ 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. +The invocation `uv run example.py` would run _isolated_ from the project with only the given +dependencies listed. ## Projects with many packages -If working in a project composed of 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/concepts/python-versions.md b/docs/concepts/python-versions.md index a7908d841996..caae8310dee0 100644 --- a/docs/concepts/python-versions.md +++ b/docs/concepts/python-versions.md @@ -1,6 +1,8 @@ # Python versions -A Python version is composed of a Python interpreter (i.e. the `python` executable), the standard library, and other supporting files. It is common for an operating system to come with a Python version installed. +A Python version is composed of a Python interpreter (i.e. the `python` executable), the standard +library, and other supporting files. It is common for an operating system to come with a Python +version installed. ## Requesting a version @@ -12,7 +14,8 @@ For example, when creating a virtual environment: uv venv --python 3.11.6 ``` -uv will ensure that Python 3.11.6 is available — downloading and installing it if necessary — then create the virtual environment with it. +uv will ensure that Python 3.11.6 is available — downloading and installing it if necessary — then +create the virtual environment with it. Many Python version request formats are supported: @@ -56,15 +59,18 @@ uv python install 3.9 3.10 3.11 ## Project Python versions -By default `uv python install` will verify that a managed Python version is installed or install the latest version. +By default `uv python install` will verify that a managed Python version is installed or install the +latest version. -However, a project may define a `.python-version` file specifying the default Python version to be used. If present, -uv will install the Python version listed in the file. +However, a project may define a `.python-version` file specifying the default Python version to be +used. If present, uv will install the Python version listed in the file. -Alternatively, a project that requires multiple Python versions may also define a `.python-versions` file. If present, -uv will install all of the Python versions listed in the file. This file takes precedence over the `.python-version` file. +Alternatively, a project that requires multiple Python versions may also define a `.python-versions` +file. If present, uv will install all of the Python versions listed in the file. This file takes +precedence over the `.python-version` file. -uv will also respect Python requirements defined in a `pyproject.toml` file during project command invocations. +uv will also respect Python requirements defined in a `pyproject.toml` file during project command +invocations. ## Viewing available Python versions @@ -96,16 +102,20 @@ uv python list --only-installed ## Adjusting Python version preferences -By default, uv will attempt to use Python versions found on the system and only download managed interpreters when necessary. -However, It's possible to adjust uv's Python version selection preference with the `python-preference` option. +By default, uv will attempt to use Python versions found on the system and only download managed +interpreters when necessary. However, It's possible to adjust uv's Python version selection +preference with the `python-preference` option. - `only-managed`: Only use managed Python installations; never use system Python installations -- `installed`: Prefer installed Python installations, only download managed Python installations if no system Python installation is found -- `managed`: Prefer managed Python installations over system Python installations, even if fetching is required +- `installed`: Prefer installed Python installations, only download managed Python installations + if no system Python installation is found +- `managed`: Prefer managed Python installations over system Python installations, even if + fetching is required - `system`: Prefer system Python installations over managed Python installations - `only-system`: Only use system Python installations; never use managed Python installations -These options allow disabling uv's managed Python versions entirely or always using them and ignoring any existing system installations. +These options allow disabling uv's managed Python versions entirely or always using them and +ignoring any existing system installations. ## Discovery order @@ -116,16 +126,24 @@ When searching for a Python version, the following locations are checked: - On Windows, the Python interpreter returned by `py --list-paths` that matches the requested version. -If a specific Python version is requested, e.g. `--python 3.7`, additional executable names are included in the search: +If a specific Python version is requested, e.g. `--python 3.7`, additional executable names are +included in the search: - A Python interpreter on the `PATH` as, e.g., `python3.7` on macOS and Linux. ## Python distributions -Python does not publish official distributable CPython binaries, uv uses third-party standalone distributions from the [`python-build-standalone`](https://github.com/indygreg/python-build-standalone) project. The project is partially maintained by the uv maintainers and is used by many other Python projects. +Python does not publish official distributable CPython binaries, uv uses third-party standalone +distributions from the +[`python-build-standalone`](https://github.com/indygreg/python-build-standalone) project. The +project is partially maintained by the uv maintainers and is used by many other Python projects. -The Python distributions are self-contained and highly-portable. Additionally, these distributions have various build-time optimizations enabled to ensure they are performant. +The Python distributions are self-contained and highly-portable. Additionally, these distributions +have various build-time optimizations enabled to ensure they are performant. -These distributions have some behavior quirks, generally as a consequence of portability. See the [`python-build-standalone` quirks](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html) documentation for details. +These distributions have some behavior quirks, generally as a consequence of portability. See the +[`python-build-standalone` +quirks](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html) documentation for +details. PyPy distributions are provided by the PyPy project. diff --git a/docs/concepts/resolution.md b/docs/concepts/resolution.md index 64f403fac961..e021b60877fd 100644 --- a/docs/concepts/resolution.md +++ b/docs/concepts/resolution.md @@ -2,13 +2,13 @@ ## Resolution strategy -By default, uv follows the standard Python dependency resolution strategy of preferring the -latest compatible version of each package. For example, `uv pip install flask>=2.0.0` will -install the latest version of Flask (at time of writing: `3.0.0`). +By default, uv follows the standard Python dependency resolution strategy of preferring the latest +compatible version of each package. For example, `uv pip install flask>=2.0.0` will install the +latest version of Flask (at time of writing: `3.0.0`). However, uv's resolution strategy can be configured to support alternative workflows. With -`--resolution=lowest`, uv will install the **lowest** compatible versions for all dependencies, -both **direct** and **transitive**. Alternatively, `--resolution=lowest-direct` will opt for the +`--resolution=lowest`, uv will install the **lowest** compatible versions for all dependencies, both +**direct** and **transitive**. Alternatively, `--resolution=lowest-direct` will opt for the **lowest** compatible versions for all **direct** dependencies, while using the **latest** compatible versions for all **transitive** dependencies. This distinction can be particularly useful for library authors who wish to test against the lowest supported versions of direct dependencies @@ -68,36 +68,37 @@ By default, uv will accept pre-release versions during dependency resolution in (e.g., `flask>=2.0.0rc1`). 1. If _all_ published versions of a package are pre-releases. -If dependency resolution fails due to a transitive pre-release, uv will prompt the user to -re-run with `--prerelease=allow`, to allow pre-releases for all dependencies. +If dependency resolution fails due to a transitive pre-release, uv will prompt the user to re-run +with `--prerelease=allow`, to allow pre-releases for all dependencies. Alternatively, you can add the transitive dependency to your `requirements.in` file with a pre-release specifier (e.g., `flask>=2.0.0rc1`) to opt in to pre-release support for that specific dependency. -Pre-releases are [notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) -to model, and are a frequent source of bugs in other packaging tools. uv's pre-release handling -is _intentionally_ limited and _intentionally_ requires user opt-in for pre-releases, to ensure -correctness. +Pre-releases are [notoriously +difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to model, and are a +frequent source of bugs in other packaging tools. uv's pre-release handling is _intentionally_ +limited and _intentionally_ requires user opt-in for pre-releases, to ensure correctness. For more, see ["Pre-release compatibility"](../pip/compatibility.md#pre-release-compatibility) ## Dependency overrides -Historically, `pip` has supported "constraints" (`-c constraints.txt`), which allows users to -narrow the set of acceptable versions for a given package. +Historically, `pip` has supported "constraints" (`-c constraints.txt`), which allows users to narrow +the set of acceptable versions for a given package. uv supports constraints, but also takes this concept further by allowing users to _override_ the -acceptable versions of a package across the dependency tree via overrides (`--override overrides.txt`). +acceptable versions of a package across the dependency tree via overrides (`--override +overrides.txt`). -In short, overrides allow the user to lie to the resolver by overriding the declared dependencies -of a package. Overrides are a useful last resort for cases in which the user knows that a -dependency is compatible with a newer version of a package than the package declares, but the -package has not yet been updated to declare that compatibility. +In short, overrides allow the user to lie to the resolver by overriding the declared dependencies of +a package. Overrides are a useful last resort for cases in which the user knows that a dependency is +compatible with a newer version of a package than the package declares, but the package has not yet +been updated to declare that compatibility. -For example, if a transitive dependency declares `pydantic>=1.0,<2.0`, but the user knows that -the package is compatible with `pydantic>=2.0`, the user can override the declared dependency -with `pydantic>=2.0,<3` to allow the resolver to continue. +For example, if a transitive dependency declares `pydantic>=1.0,<2.0`, but the user knows that the +package is compatible with `pydantic>=2.0`, the user can override the declared dependency with +`pydantic>=2.0,<3` to allow the resolver to continue. While constraints are purely _additive_, and thus cannot _expand_ the set of acceptable versions for a package, overrides _can_ expand the set of acceptable versions for a package, providing an escape @@ -105,34 +106,34 @@ hatch for erroneous upper version bounds. ## Multi-platform resolution -By default, uv's `pip-compile` command produces a resolution that's known to be compatible with -the current platform and Python version. +By default, uv's `pip-compile` command produces a resolution that's known to be compatible with the +current platform and Python version. -uv also supports a machine agnostic resolution. uv supports writing multiplatform resolutions in both a `requirements.txt` format -and uv-specific (`uv.lock`) format. +uv also supports a machine agnostic resolution. uv supports writing multiplatform resolutions in +both a `requirements.txt` format and uv-specific (`uv.lock`) format. -If using uv's `pip compile`, the `--universal` flag will generate a resolution that is compatible with all operating systems, -architectures, and Python implementations. In universal mode, the current Python version (or provided `--python-version`) -will be treated as a lower bound. For example, `--universal --python-version 3.7` would produce a universal resolution -for Python 3.7 and later. +If using uv's `pip compile`, the `--universal` flag will generate a resolution that is compatible +with all operating systems, architectures, and Python implementations. In universal mode, the +current Python version (or provided `--python-version`) will be treated as a lower bound. For +example, `--universal --python-version 3.7` would produce a universal resolution for Python 3.7 and +later. -If using uv's [project](../guides/projects.md) interface, the machine agnostic resolution will be used -automatically and a `uv.lock` file will be created. The lockfile can also be created with an explicit `uv lock` -invocation. +If using uv's [project](../guides/projects.md) interface, the machine agnostic resolution will be +used automatically and a `uv.lock` file will be created. The lockfile can also be created with an +explicit `uv lock` invocation. uv also supports resolving for specific alternate platforms and Python versions via the `--python-platform` and `--python-version` command line arguments. -For example, if you're running uv on macOS, but want to resolve for Linux, you can run -`uv pip compile --python-platform=linux requirements.in` to produce a `manylinux2014`-compatible -resolution. +For example, if you're running uv on macOS, but want to resolve for Linux, you can run `uv pip +compile --python-platform=linux requirements.in` to produce a `manylinux2014`-compatible resolution. -Similarly, if you're running uv on Python 3.9, but want to resolve for Python 3.8, you can run -`uv pip compile --python-version=3.8 requirements.in` to produce a Python 3.8-compatible resolution. +Similarly, if you're running uv on Python 3.9, but want to resolve for Python 3.8, you can run `uv +pip compile --python-version=3.8 requirements.in` to produce a Python 3.8-compatible resolution. The `--python-platform` and `--python-version` arguments can be combined to produce a resolution for -a specific platform and Python version, enabling users to generate multiple lockfiles for -different environments from a single machine. +a specific platform and Python version, enabling users to generate multiple lockfiles for different +environments from a single machine. !!! note @@ -146,13 +147,15 @@ different environments from a single machine. ## Time-restricted reproducible resolutions -uv supports an `--exclude-newer` option to limit resolution to distributions published before a specific -date, allowing reproduction of installations regardless of new package releases. The date may be specified -as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamp (e.g., `2006-12-02T02:07:43Z`) or -UTC date in the same format (e.g., `2006-12-02`). +uv supports an `--exclude-newer` option to limit resolution to distributions published before a +specific date, allowing reproduction of installations regardless of new package releases. The date +may be specified as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamp (e.g., +`2006-12-02T02:07:43Z`) or UTC date in the same format (e.g., `2006-12-02`). -Note the package index must support the `upload-time` field as specified in [`PEP 700`](https://peps.python.org/pep-0700/). -If the field is not present for a given distribution, the distribution will be treated as unavailable. +Note the package index must support the `upload-time` field as specified in [`PEP +700`](https://peps.python.org/pep-0700/). If the field is not present for a given distribution, the +distribution will be treated as unavailable. -To ensure reproducibility, messages for unsatisfiable resolutions will not mention that distributions were excluded -due to the `--exclude-newer` flag — newer distributions will be treated as if they do not exist. +To ensure reproducibility, messages for unsatisfiable resolutions will not mention that +distributions were excluded due to the `--exclude-newer` flag — newer distributions will be treated +as if they do not exist. diff --git a/docs/concepts/tools.md b/docs/concepts/tools.md index 62f20ece1b41..5a0a6254b253 100644 --- a/docs/concepts/tools.md +++ b/docs/concepts/tools.md @@ -1,18 +1,27 @@ # Tools -Tools are Python packages that provide command-line interfaces. Tools can be invoked without installation using `uvx`, in which case their dependencies are installed in a temporary virtual environment isolated from the current project. Alternatively, tools can be installed with `uv tool install`, in which case their executables are placed in the `PATH` — an isolated virtual environment is still used but it is not treated as disposable. +Tools are Python packages that provide command-line interfaces. Tools can be invoked without +installation using `uvx`, in which case their dependencies are installed in a temporary virtual +environment isolated from the current project. Alternatively, tools can be installed with `uv tool +install`, in which case their executables are placed in the `PATH` — an isolated virtual environment +is still used but it is not treated as disposable. !!! note - See the [tools guide](../guides/tools.md) for an introduction to working with the tools interface — this document discusses details of tool management. + See the [tools guide](../guides/tools.md) for an introduction to working with the tools + interface — this document discusses details of tool management. ## Tool environments -Tools are installed into virtual environments which are created in the uv tools directory. When running tools with `uvx` or `uv tool run`, the virtual environments are stored in the uv cache directory and are treated as disposable. +Tools are installed into virtual environments which are created in the uv tools directory. When +running tools with `uvx` or `uv tool run`, the virtual environments are stored in the uv cache +directory and are treated as disposable. ### Tools directory -By default, the uv tools directory is named `tools` and is in the uv application state directory, e.g., `~/.local/share/uv/tools`. The location may be customized with the `UV_TOOL_DIR` environment variable. +By default, the uv tools directory is named `tools` and is in the uv application state directory, +e.g., `~/.local/share/uv/tools`. The location may be customized with the `UV_TOOL_DIR` environment +variable. To display the path to the tool installation directory: @@ -20,11 +29,13 @@ To display the path to the tool installation directory: $ uv tool dir ``` -Tool environments are placed in a directory with the same name as the tool package, e.g., `.../tools/`. +Tool environments are placed in a directory with the same name as the tool package, e.g., +`.../tools/`. ### Mutating tool environments -Tool environments are _not_ intended to be mutated directly. It is strongly recommended never to mutate a tool environment manually with a `pip` operation. +Tool environments are _not_ intended to be mutated directly. It is strongly recommended never to +mutate a tool environment manually with a `pip` operation. Tool environments may be either mutated or re-created by subsequent `uv tool install` operations. @@ -74,15 +85,22 @@ The `--with` option supports package specifications, so a specific version can b $ uvx --with == ``` -If the requested version conflicts with the requirements of the tool package, package resolution will fail and the command will error. +If the requested version conflicts with the requirements of the tool package, package resolution +will fail and the command will error. ## Tool executables -Tool executables are all console entry points, script entry points, and binary scripts provided by a Python package. Tool executables are symlinked into the `bin` directory on Unix and copied on Windows. +Tool executables are all console entry points, script entry points, and binary scripts provided by a +Python package. Tool executables are symlinked into the `bin` directory on Unix and copied on +Windows. ### `bin` directory -Executables are installed into the user's `bin` directory following the XDG standard, e.g., `~/.local/bin`. Unlike other directory schemes in uv, the XDG standard is used on _all platforms_ notably including Windows and macOS — there is no clear alternative location to place executables on these platforms. The installation directory is determined from the first available environment variable: +Executables are installed into the user's `bin` directory following the XDG standard, e.g., +`~/.local/bin`. Unlike other directory schemes in uv, the XDG standard is used on _all platforms_ +notably including Windows and macOS — there is no clear alternative location to place executables on +these platforms. The installation directory is determined from the first available environment +variable: - `$XDG_BIN_HOME` - `$XDG_DATA_HOME/../bin` @@ -92,11 +110,15 @@ Executables provided by dependencies of tool packages are not installed. ### The `PATH` -The `bin` directory must be in the `PATH` variable for tool executables to be available from the shell. If it is not in the `PATH`, a warning will be displayed. The `uv tool update-shell` command can be used to add the `bin` directory to the `PATH` in common shell configuration files. +The `bin` directory must be in the `PATH` variable for tool executables to be available from the +shell. If it is not in the `PATH`, a warning will be displayed. The `uv tool update-shell` command +can be used to add the `bin` directory to the `PATH` in common shell configuration files. ### Overriding executables -Installation of tools will not overwrite executables in the `bin` directory that were not previously installed by uv. For example, if `pipx` has been used to install a tool, `uv tool install` will fail. The `--force` flag can be used to override this behavior. +Installation of tools will not overwrite executables in the `bin` directory that were not previously +installed by uv. For example, if `pipx` has been used to install a tool, `uv tool install` will +fail. The `--force` flag can be used to override this behavior. ## `uv tool run` vs `uv run` @@ -111,4 +133,5 @@ However, there are a couple notable differences when using uv's tool interface: - The `--with` option is not needed — the required package is inferred from the command name. - The temporary environment is cached in a dedicated location. - The `--isolated` flag is not needed — tools are always run isolated from the project. -- If a tool is already installed, `uv tool run` will use the installed version but `uv run` will not. +- If a tool is already installed, `uv tool run` will use the installed version but `uv run` will + not. diff --git a/docs/concepts/workspaces.md b/docs/concepts/workspaces.md index 34c8def9eaa7..bd7a36c682e3 100644 --- a/docs/concepts/workspaces.md +++ b/docs/concepts/workspaces.md @@ -1,18 +1,18 @@ # Workspaces -Workspaces help organize large codebases by splitting them into multiple packages with -independent dependencies. +Workspaces help organize large codebases by splitting them into multiple packages with independent +dependencies. When using the `uv pip` interface, workspace dependencies behave like automatic editable path -dependencies. Using the uv project interface, all of the workspace packages are locked together. -`uv run` installs only the current package (unless overridden with `--package`) and its workspace and +dependencies. Using the uv project interface, all of the workspace packages are locked together. `uv +run` installs only the current package (unless overridden with `--package`) and its workspace and non-workspace dependencies. ## Configuration -A workspace can be created by adding a `tool.uv.workspace` to a `pyproject.toml` that is the workspace -root. This table contains `members` (mandatory) and `exclude` (optional), with lists of globs of -directories: +A workspace can be created by adding a `tool.uv.workspace` to a `pyproject.toml` that is the +workspace root. This table contains `members` (mandatory) and `exclude` (optional), with lists of +globs of directories: ```toml title="pyproject.toml" [tool.uv.workspace] @@ -20,14 +20,16 @@ members = ["packages/*", "examples/*"] exclude = ["example/excluded_example"] ``` -If `tool.uv.sources` is defined in the workspace root, it applies to all packages, unless -overridden in the `tool.uv.sources` of a specific project. +If `tool.uv.sources` is defined in the workspace root, it applies to all packages, unless overridden +in the `tool.uv.sources` of a specific project. ## Common structures There a two main workspace structures: A **root package with helpers** and a **flat workspace**. -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. +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 @@ -52,9 +54,9 @@ albatross └── main.py ``` -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`. +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 diff --git a/docs/configuration/authentication.md b/docs/configuration/authentication.md index 6bbfc1a917fb..91163d5c7972 100644 --- a/docs/configuration/authentication.md +++ b/docs/configuration/authentication.md @@ -2,25 +2,31 @@ ## Git authentication -uv allows packages to be installed from Git and supports the following schemes for authenticating with private -repositories. +uv allows packages to be installed from Git and supports the following schemes for authenticating +with private repositories. Using SSH: - `git+ssh://git@/...` (e.g. `git+ssh://git@github.com/astral-sh/uv`) - `git+ssh://git@/...` (e.g. `git+ssh://git@github.com-key-2/astral-sh/uv`) -See the [GitHub SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh) for more details on how to configure SSH. +See the [GitHub SSH +documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh) +for more details on how to configure SSH. Using a password or token: -- `git+https://:@/...` (e.g. `git+https://git:github_pat_asdf@github.com/astral-sh/uv`) +- `git+https://:@/...` (e.g. + `git+https://git:github_pat_asdf@github.com/astral-sh/uv`) - `git+https://@/...` (e.g. `git+https://github_pat_asdf@github.com/astral-sh/uv`) - `git+https://@/...` (e.g. `git+https://git@github.com/astral-sh/uv`) -When using a GitHub personal access token, the username is arbitrary. GitHub does not support logging in with password directly, although other hosts may. If a username is provided without credentials, you will be prompted to enter them. +When using a GitHub personal access token, the username is arbitrary. GitHub does not support +logging in with password directly, although other hosts may. If a username is provided without +credentials, you will be prompted to enter them. -If there are no credentials present in the URL and authentication is needed, the [Git credential helper](https://git-scm.com/doc/credential-helpers) will be queried. +If there are no credentials present in the URL and authentication is needed, the [Git credential +helper](https://git-scm.com/doc/credential-helpers) will be queried. ## HTTP authentication @@ -32,12 +38,12 @@ Authentication can come from the following sources, in order of precedence: - A [`netrc`](https://everything.curl.dev/usingcurl/netrc) configuration file - A [keyring](https://github.com/jaraco/keyring) provider (requires opt-in) -If authentication is found for a single net location (scheme, host, and port), it will be cached for the duration -of the command and used for other queries to that net location. Authentication is not cached across invocations of -uv. +If authentication is found for a single net location (scheme, host, and port), it will be cached for +the duration of the command and used for other queries to that net location. Authentication is not +cached across invocations of uv. -Note `--keyring-provider subprocess` or `UV_KEYRING_PROVIDER=subprocess` must be provided to enable keyring-based -authentication. +Note `--keyring-provider subprocess` or `UV_KEYRING_PROVIDER=subprocess` must be provided to enable +keyring-based authentication. Authentication may be used for hosts specified in the following contexts: @@ -46,8 +52,8 @@ Authentication may be used for hosts specified in the following contexts: - `find-links` - `package @ https://...` -See the [`pip` compatibility guide](../pip/compatibility.md#registry-authentication) for details on differences from -`pip`. +See the [`pip` compatibility guide](../pip/compatibility.md#registry-authentication) for details on +differences from `pip`. ## Custom CA certificates @@ -65,8 +71,10 @@ variable to the path of the certificate bundle, to instruct uv to use that file system's trust store. If client certificate authentication (mTLS) is desired, set the `SSL_CLIENT_CERT` environment -variable to the path of the PEM formatted file containing the certificate followed by the private key. +variable to the path of the PEM formatted file containing the certificate followed by the private +key. ## Authentication with alternative package indexes -See the [alternative indexes integration guide](../guides/integration/alternative-indexes.md) for details on authentication with popular alternative Python package indexes. +See the [alternative indexes integration guide](../guides/integration/alternative-indexes.md) for +details on authentication with popular alternative Python package indexes. diff --git a/docs/configuration/environment.md b/docs/configuration/environment.md index 520d17bc5784..26ec11a64163 100644 --- a/docs/configuration/environment.md +++ b/docs/configuration/environment.md @@ -4,8 +4,8 @@ uv accepts the following command-line arguments as environment variables: - `UV_INDEX_URL`: Equivalent to the `--index-url` command-line argument. If set, uv will use this URL as the base index for searching for packages. -- `UV_EXTRA_INDEX_URL`: Equivalent to the `--extra-index-url` command-line argument. If set, uv - will use this space-separated list of URLs as additional indexes when searching for packages. +- `UV_EXTRA_INDEX_URL`: Equivalent to the `--extra-index-url` command-line argument. If set, uv will + use this space-separated list of URLs as additional indexes when searching for packages. - `UV_CACHE_DIR`: Equivalent to the `--cache-dir` command-line argument. If set, uv will use this directory for caching instead of the default cache directory. - `UV_NO_CACHE`: Equivalent to the `--no-cache` command-line argument. If set, uv will not use the @@ -14,30 +14,28 @@ uv accepts the following command-line arguments as environment variables: `lowest-direct`, uv will install the lowest compatible versions of all direct dependencies. - `UV_PRERELEASE`: Equivalent to the `--prerelease` command-line argument. For example, if set to `allow`, uv will allow pre-release versions for all dependencies. -- `UV_SYSTEM_PYTHON`: Equivalent to the `--system` command-line argument. If set to `true`, uv - will use the first Python interpreter found in the system `PATH`. - WARNING: `UV_SYSTEM_PYTHON=true` is intended for use in continuous integration (CI) or - containerized environments and should be used with caution, as modifying the system Python - can lead to unexpected behavior. -- `UV_PYTHON`: Equivalent to the `--python` command-line argument. If set to a path, uv will - use this Python interpreter for all operations. +- `UV_SYSTEM_PYTHON`: Equivalent to the `--system` command-line argument. If set to `true`, uv will + use the first Python interpreter found in the system `PATH`. WARNING: `UV_SYSTEM_PYTHON=true` is + intended for use in continuous integration (CI) or containerized environments and should be used + with caution, as modifying the system Python can lead to unexpected behavior. +- `UV_PYTHON`: Equivalent to the `--python` command-line argument. If set to a path, uv will use + this Python interpreter for all operations. - `UV_BREAK_SYSTEM_PACKAGES`: Equivalent to the `--break-system-packages` command-line argument. If set to `true`, uv will allow the installation of packages that conflict with system-installed - packages. - WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration (CI) or - containerized environments and should be used with caution, as modifying the system Python + packages. WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration + (CI) or containerized environments and should be used with caution, as modifying the system Python can lead to unexpected behavior. -- `UV_NATIVE_TLS`: Equivalent to the `--native-tls` command-line argument. If set to `true`, uv - will use the system's trust store instead of the bundled `webpki-roots` crate. +- `UV_NATIVE_TLS`: Equivalent to the `--native-tls` command-line argument. If set to `true`, uv will + use the system's trust store instead of the bundled `webpki-roots` crate. - `UV_INDEX_STRATEGY`: Equivalent to the `--index-strategy` command-line argument. For example, if - set to `unsafe-any-match`, uv will consider versions of a given package available across all - index URLs, rather than limiting its search to the first index URL that contains the package. + set to `unsafe-any-match`, uv will consider versions of a given package available across all index + URLs, rather than limiting its search to the first index URL that contains the package. - `UV_REQUIRE_HASHES`: Equivalent to the `--require-hashes` command-line argument. If set to `true`, uv will require that all dependencies have a hash specified in the requirements file. - `UV_CONSTRAINT`: Equivalent to the `--constraint` command-line argument. If set, uv will use this file as the constraints file. Uses space-separated list of files. -- `UV_LINK_MODE`: Equivalent to the `--link-mode` command-line argument. If set, uv will use this - as a link mode. +- `UV_LINK_MODE`: Equivalent to the `--link-mode` command-line argument. If set, uv will use this as + a link mode. - `UV_NO_BUILD_ISOLATION`: Equivalent to the `--no-build-isolation` command-line argument. If set, uv will skip isolation when building source distributions. - `UV_CUSTOM_COMPILE_COMMAND`: Used to override uv in the output header of the `requirements.txt` @@ -47,8 +45,8 @@ uv accepts the following command-line arguments as environment variables: will use this value as the keyring provider. - `UV_CONFIG_FILE`: Equivalent to the `--config-file` command-line argument. Expects a path to a local `uv.toml` file to use as the configuration file. -- `UV_CONCURRENT_DOWNLOADS`: Sets the maximum number of in-flight concurrent downloads that uv - will perform at any given time. +- `UV_CONCURRENT_DOWNLOADS`: Sets the maximum number of in-flight concurrent downloads that uv will + perform at any given time. - `UV_CONCURRENT_BUILDS`: Sets the maximum number of source distributions that uv will build concurrently at any given time. - `UV_CONCURRENT_INSTALLS`: Used to control the number of threads used when installing and unzipping @@ -66,13 +64,14 @@ In addition, uv respects the following environment variables: file containing both the certificate and the private key in PEM format. - `RUST_LOG`: If set, uv will use this value as the log level for its `--verbose` output. Accepts any filter compatible with the `tracing_subscriber` crate. For example, `RUST_LOG=trace` will - enable trace-level logging. See the [tracing documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax) + enable trace-level logging. See the [tracing + documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax) for more. - `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`: The proxy to use for all HTTP/HTTPS requests. - `HTTP_TIMEOUT` (or `UV_HTTP_TIMEOUT`): If set, uv will use this value (in seconds) as the timeout for HTTP reads (default: 30 s). -- `PYC_INVALIDATION_MODE`: The validation modes to use when run with `--compile`. - See: [`PycInvalidationMode`](https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode). +- `PYC_INVALIDATION_MODE`: The validation modes to use when run with `--compile`. See: + [`PycInvalidationMode`](https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode). - `VIRTUAL_ENV`: Used to detect an activated virtual environment. - `CONDA_PREFIX`: Used to detect an activated Conda environment. - `PROMPT`: Used to detect the use of the Windows Command Prompt (as opposed to PowerShell). @@ -83,5 +82,7 @@ In addition, uv respects the following environment variables: - `MACOSX_DEPLOYMENT_TARGET`: Used with `--python-platform macos` and related variants to set the deployment target (i.e., the minimum supported macOS version). Defaults to `12.0`, the least-recent non-EOL macOS version at time of writing. -- `NO_COLOR`: Disable colors. Takes precedence over `FORCE_COLOR`. See [no-color.org](https://no-color.org). -- `FORCE_COLOR`: Enforce colors regardless of TTY support. See [force-color.org](https://force-color.org). +- `NO_COLOR`: Disable colors. Takes precedence over `FORCE_COLOR`. See + [no-color.org](https://no-color.org). +- `FORCE_COLOR`: Enforce colors regardless of TTY support. See + [force-color.org](https://force-color.org). diff --git a/docs/configuration/files.md b/docs/configuration/files.md index 0a46aa305173..d8f90edc6982 100644 --- a/docs/configuration/files.md +++ b/docs/configuration/files.md @@ -5,16 +5,16 @@ uv supports persistent configuration files at both the project- and user-level. Specifically, uv will search for a `pyproject.toml` or `uv.toml` file in the current directory, or 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`: +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 title="project.toml" [tool.uv.pip] index-url = "https://test.pypi.org/simple" ``` -(If there is no such table, the `pyproject.toml` file will be ignored, and uv will continue searching in -the directory hierarchy.) +(If there is no such table, the `pyproject.toml` file will be ignored, and uv will continue +searching in the directory hierarchy.) If a `uv.toml` file is found, uv will read from the `[pip]` table. For example: diff --git a/docs/configuration/index.md b/docs/configuration/index.md index ec3572c8a4f1..463d00a9c01b 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -8,4 +8,5 @@ Read about the various ways to configure uv: -Or, jump to the [settings reference](../settings.md) which enumerates the available configuration options. +Or, jump to the [settings reference](../settings.md) which enumerates the available configuration +options. diff --git a/docs/features.md b/docs/features.md index 562d4dc39cdb..7c03e7d46a48 100644 --- a/docs/features.md +++ b/docs/features.md @@ -1,9 +1,11 @@ # 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. +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. -uv's commands can be broken down into sections of discrete features, which can be used independently. +uv's commands can be broken down into sections of discrete features, which can be used +independently. ## Python versions @@ -53,7 +55,8 @@ See the [guide on tools](./guides/tools.md) to get started. ## The pip interface -Manually managing environments and packages — intended to be used in legacy workflows or cases where the high-level commands do not provide enough control. +Manually managing environments and packages — intended to be used in legacy workflows or cases where +the high-level commands do not provide enough control. Creating virtual environments (replacing `venv` and `virtualenv`): @@ -61,7 +64,8 @@ Creating virtual environments (replacing `venv` and `virtualenv`): See the documentation on [using environments](./pip/environments.md) for details. -Managing packages in an environment (replacing [`pip`](https://github.com/pypa/pip) and [`pipdeptree`](https://github.com/tox-dev/pipdeptree)): +Managing packages in an environment (replacing [`pip`](https://github.com/pypa/pip) and +[`pipdeptree`](https://github.com/tox-dev/pipdeptree)): - `uv pip install`: Install packages into the current environment. - `uv pip show`: Show details about an installed package. @@ -86,7 +90,8 @@ See the documentation on [locking environments](./pip/compile.md) for details. ## Internal -Managing and inspecting uv's state, such as the cache, storage directories, or performing a self-update: +Managing and inspecting uv's state, such as the cache, storage directories, or performing a +self-update: - `uv cache clean`: Remove cache entries. - `uv cache prune`: Remove outdated cache entries. diff --git a/docs/first-steps.md b/docs/first-steps.md index 2344cc6bc96a..bf214619456e 100644 --- a/docs/first-steps.md +++ b/docs/first-steps.md @@ -2,7 +2,8 @@ uv only provides a command-line interface and must be used from a terminal. -After [installing uv](./installation.md), you can check that uv is installed by running the `uv` command: +After [installing uv](./installation.md), you can check that uv is installed by running the `uv` +command: ```console $ uv @@ -40,7 +41,8 @@ To view the help menu for a specific command, e.g., for `uv init`: $ uv init --help ``` -When using the `--help` flag, uv displays a condensed help menu. To view a longer help menu for a command, use `uv help`: +When using the `--help` flag, uv displays a condensed help menu. To view a longer help menu for a +command, use `uv help`: ```console $ uv help @@ -52,8 +54,10 @@ To view the long help menu for a specific command, e.g., for `uv init`: $ uv help init ``` -When using the long help menu, uv will attempt to use `less` or `more` to "page" the output so it is not all displayed at once. To exit the pager, press `q`. +When using the long help menu, uv will attempt to use `less` or `more` to "page" the output so it is +not all displayed at once. To exit the pager, press `q`. ## Next steps -Now that you've confirmed uv is installed and know how to get help, check out an [overview of features](./features.md) or jump straight into the [guides](./guides/index.md) to start using uv. +Now that you've confirmed uv is installed and know how to get help, check out an [overview of +features](./features.md) or jump straight into the [guides](./guides/index.md) to start using uv. diff --git a/docs/guides/index.md b/docs/guides/index.md index 1a96d15f2866..faf9ee955f4f 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -14,4 +14,5 @@ Learn how to integrate uv with other software: - [Using in GitHub Actions](./integration/github.md) - [Using with alternative package indexes](./integration/alternative-indexes.md) -Or, explore the [concept documentation](../concepts/index.md) for comprehensive breakdown of each feature. +Or, explore the [concept documentation](../concepts/index.md) for comprehensive breakdown of each +feature. diff --git a/docs/guides/install-python.md b/docs/guides/install-python.md index da9b384ceadf..a97187760797 100644 --- a/docs/guides/install-python.md +++ b/docs/guides/install-python.md @@ -1,6 +1,8 @@ # Installing Python -If Python is already installed on your system, uv will [detect and use](#using-an-existing-python-installation) it without configuration. However, uv can also install and manage Python versions for you. +If Python is already installed on your system, uv will [detect and +use](#using-an-existing-python-installation) it without configuration. However, uv can also install +and manage Python versions for you. !!! tip @@ -12,7 +14,8 @@ To install the latest Python version: $ uv python install ``` -This will install a uv managed Python version even if there is already a Python installation on your system. +This will install a uv managed Python version even if there is already a Python installation on your +system. !!! note @@ -41,7 +44,8 @@ To install a specific Python version: $ uv python install 3.12 ``` -See the [`python install`](../concepts/python-versions.md#installing-a-python-version) documentation for more details. +See the [`python install`](../concepts/python-versions.md#installing-a-python-version) documentation +for more details. ## Viewing Python installations @@ -51,19 +55,24 @@ To view available and installed Python versions: $ uv python list ``` -See the [`python list`](../concepts/python-versions.md#viewing-available-python-versions) documentation for more details. +See the [`python list`](../concepts/python-versions.md#viewing-available-python-versions) +documentation for more details. ## Automatic Python downloads -Note that Python does not need to be explicitly installed to use uv. By default, uv will automatically download Python versions when they are required. For example, the following would download Python 3.12 if it was not installed: +Note that Python does not need to be explicitly installed to use uv. By default, uv will +automatically download Python versions when they are required. For example, the following would +download Python 3.12 if it was not installed: ```console $ uv run --python 3.12 python -c 'print("hello world")' ``` -Even if a specific Python version is not requested, uv will download the latest version on demand. For example, the following will create a new virtual environment and download a managed Python version if Python is not found: +Even if a specific Python version is not requested, uv will download the latest version on demand. +For example, the following will create a new virtual environment and download a managed Python +version if Python is not found: ```console $ uv venv @@ -75,6 +84,11 @@ Note that when an automatic Python installation occurs, the `python` command wil ## Using an existing Python installation -uv will also use an existing Python installation if already present on your system. There is no configuration necessary for this behavior: uv will use the system Python if it satisfies the requirements of the command invocation. See the [Python discovery](../concepts/python-versions.md#discovery-order) documentation for details. +uv will also use an existing Python installation if already present on your system. There is no +configuration necessary for this behavior: uv will use the system Python if it satisfies the +requirements of the command invocation. See the [Python +discovery](../concepts/python-versions.md#discovery-order) documentation for details. -To force uv to use the system Python, provide the `--python-preference only-system` option. See the [Python version preference](../concepts/python-versions.md#adjusting-python-version-preferences) documentation for more details. +To force uv to use the system Python, provide the `--python-preference only-system` option. See the +[Python version preference](../concepts/python-versions.md#adjusting-python-version-preferences) +documentation for more details. diff --git a/docs/guides/integration/alternative-indexes.md b/docs/guides/integration/alternative-indexes.md index c456fa2ea49c..ab393467e3c4 100644 --- a/docs/guides/integration/alternative-indexes.md +++ b/docs/guides/integration/alternative-indexes.md @@ -1,14 +1,23 @@ # Using alternative package indexes -While uv uses the official Python Package Index (PyPI) by default, it also supports alternative package indexes. Most alternative indexes require various forms of authentication, which requires some initial setup. +While uv uses the official Python Package Index (PyPI) by default, it also supports alternative +package indexes. Most alternative indexes require various forms of authentication, which requires +some initial setup. ## Azure Artifacts -uv can install packages from [Azure DevOps Artifacts](https://learn.microsoft.com/en-us/azure/devops/artifacts/start-using-azure-artifacts?view=azure-devops&tabs=nuget%2Cnugetserver). Authenticate to a feed using a [Personal Access Token](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows) (PAT) or interactively using the [`keyring`](https://github.com/jaraco/keyring) package. +uv can install packages from [Azure DevOps +Artifacts](https://learn.microsoft.com/en-us/azure/devops/artifacts/start-using-azure-artifacts?view=azure-devops&tabs=nuget%2Cnugetserver). +Authenticate to a feed using a [Personal Access +Token](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows) +(PAT) or interactively using the [`keyring`](https://github.com/jaraco/keyring) package. ### Using a PAT -If there is a PAT available (eg [`$(System.AccessToken)` in an Azure pipeline](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken)), credentials can be provided via the "Basic" HTTP authentication scheme. Include the PAT in the password field of the URL. A username must be included as well, but can be any string. +If there is a PAT available (eg [`$(System.AccessToken)` in an Azure +pipeline](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken)), +credentials can be provided via the "Basic" HTTP authentication scheme. Include the PAT in the +password field of the URL. A username must be included as well, but can be any string. ```bash # With the token stored in the `ADO_PAT` environment variable @@ -17,11 +26,22 @@ export UV_EXTRA_INDEX_URL=https://dummy:$ADO_PAT@pkgs.dev.azure.com/{organisatio ### Using `keyring` -If there is not a PAT available, authenticate to Artifacts using the [`keyring`](https://github.com/jaraco/keyring) package with [the `artifacts-keyring` plugin](https://github.com/Microsoft/artifacts-keyring). Because these two packages are required to authenticate to Azure Artifacts, they must be pre-installed from a source other than Artifacts. +If there is not a PAT available, authenticate to Artifacts using the +[`keyring`](https://github.com/jaraco/keyring) package with [the `artifacts-keyring` +plugin](https://github.com/Microsoft/artifacts-keyring). Because these two packages are required to +authenticate to Azure Artifacts, they must be pre-installed from a source other than Artifacts. -The `artifacts-keyring` plugin wraps [the Azure Artifacts Credential Provider tool](https://github.com/microsoft/artifacts-credprovider). The credential provider supports a few different authentication modes including interactive login — see [the tool's documentation](https://github.com/microsoft/artifacts-credprovider) for information on configuration. +The `artifacts-keyring` plugin wraps [the Azure Artifacts Credential Provider +tool](https://github.com/microsoft/artifacts-credprovider). The credential provider supports a few +different authentication modes including interactive login — see [the tool's +documentation](https://github.com/microsoft/artifacts-credprovider) for information on +configuration. -uv only supports using the `keyring` package in [subprocess mode](https://github.com/astral-sh/uv/blob/main/PIP_COMPATIBILITY.md#registry-authentication). The `keyring` executable must be in the `PATH`, i.e., installed globally or in the active environment. The `keyring` CLI requires a username in the URL, so the index URL must include the default username `VssSessionToken`. +uv only supports using the `keyring` package in [subprocess +mode](https://github.com/astral-sh/uv/blob/main/PIP_COMPATIBILITY.md#registry-authentication). The +`keyring` executable must be in the `PATH`, i.e., installed globally or in the active environment. +The `keyring` CLI requires a username in the URL, so the index URL must include the default username +`VssSessionToken`. ```bash # Pre-install keyring and the Artifacts plugin from the public PyPI @@ -36,4 +56,5 @@ export UV_EXTRA_INDEX_URL=https://VssSessionToken@pkgs.dev.azure.com/{organisati ## Other indexes -uv is also known to work with JFrog's Artifactory, the Google Cloud Artifact Registry, and AWS Code Artifact. +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 4d60ff3089cf..e821f830f85e 100644 --- a/docs/guides/integration/docker.md +++ b/docs/guides/integration/docker.md @@ -2,7 +2,8 @@ ## Running in Docker -A Docker image is published with a built version of uv available. To run a uv command in a container: +A Docker image is published with a built version of uv available. To run a uv command in a +container: ```bash docker run ghcr.io/astral-sh/uv --help @@ -34,7 +35,8 @@ In either case, it is best practice to pin to a specific uv version. 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: +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 title="Dockerfile" RUN uv pip install --system ruff @@ -73,7 +75,9 @@ RUN uv pip install -r requirements.txt ## Installing a project -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). +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 title="Dockerfile" COPY pyproject.toml . @@ -95,7 +99,8 @@ RUN --mount=from=uv,source=/uv,target=/bin/uv \ ### Caching -A [cache mount](https://docs.docker.com/build/guide/mounts/#add-a-cache-mount) can be used to improve performance across builds: +A [cache mount](https://docs.docker.com/build/guide/mounts/#add-a-cache-mount) can be used to +improve performance across builds: ```dockerfile title="Dockerfile" RUN --mount=type=cache,target=/root/.cache/uv \ diff --git a/docs/guides/integration/github.md b/docs/guides/integration/github.md index 07eed1054dd6..abdf4287491f 100644 --- a/docs/guides/integration/github.md +++ b/docs/guides/integration/github.md @@ -109,7 +109,8 @@ steps: run: uv python install ${{ matrix.python-version }} ``` -Alternatively, the official GitHub `setup-python` action can be used. This is generally faster, but will not respect the project's pinned Python version. +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 title="example.yml" steps: @@ -121,7 +122,8 @@ steps: ## Syncing and running -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`: +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 title="example.yml" steps: @@ -137,7 +139,9 @@ steps: ## Using `uv pip` -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. +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. ### Setting `UV_SYSTEM_PYTHON` @@ -178,7 +182,8 @@ steps: UV_SYSTEM_PYTHON: 1 ``` -Now, `uv pip` can modify the system environment without creating and activating a virtual environment. +Now, `uv pip` can modify the system environment without creating and activating a virtual +environment. ```yaml title="example.yml" steps: diff --git a/docs/guides/integration/pre-commit.md b/docs/guides/integration/pre-commit.md index b02712c2767a..c590bead4619 100644 --- a/docs/guides/integration/pre-commit.md +++ b/docs/guides/integration/pre-commit.md @@ -1,6 +1,7 @@ # Using uv in pre-commit -An official pre-commit hook is provided at [`astral-sh/uv-pre-commit`](https://github.com/astral-sh/uv-pre-commit). +An official pre-commit hook is provided at +[`astral-sh/uv-pre-commit`](https://github.com/astral-sh/uv-pre-commit). To compile requirements via pre-commit, add the following to the `.pre-commit-config.yaml`: diff --git a/docs/guides/projects.md b/docs/guides/projects.md index 2a970134ca72..4c7faf4ebf71 100644 --- a/docs/guides/projects.md +++ b/docs/guides/projects.md @@ -1,6 +1,7 @@ # Working on projects -uv is capable of managing Python projects using a `pyproject.toml` with a `[project]` metadata table. +uv is capable of managing Python projects using a `pyproject.toml` with a `[project]` metadata +table. ## Creating a new project @@ -32,21 +33,20 @@ This will create the following directory structure: ### Working on an existing project -If your project already contains a standard `pyproject.toml`, you can start -using uv without any extra work. Commands like `uv add` and `uv run` will -create a lockfile and virtual environment the first time they are used. +If your project already contains a standard `pyproject.toml`, you can start using uv without any +extra work. Commands like `uv add` and `uv run` will create a lockfile and virtual environment the +first time they are used. -If you are migrating from an alternative Python package manager, you may need to -edit your `pyproject.toml` manually before using uv. uv uses a `[tool.uv]` section -in the `pyproject.toml` to support features that are not yet included in the `pyproject.toml` standard, such as development dependencies. Alternative Python package managers may use -different sections or format. +If you are migrating from an alternative Python package manager, you may need to edit your +`pyproject.toml` manually before using uv. uv uses a `[tool.uv]` section in the `pyproject.toml` to +support features that are not yet included in the `pyproject.toml` standard, such as development +dependencies. Alternative Python package managers may use different sections or format. ## Project structure -A project consists of a few important parts that work together and allow uv to -manage your project. Along with the files created by `uv init`, uv will create a -virtual environment and `uv.lock` file in the root of your project the first time you -run a project command. +A project consists of a few important parts that work together and allow uv to manage your project. +Along with the files created by `uv init`, uv will create a virtual environment and `uv.lock` file +in the root of your project the first time you run a project command. ### `pyproject.toml` @@ -64,10 +64,9 @@ dependencies = [] dev-dependencies = [] ``` -This is where you specify dependencies, as well as details about the project -such as it's description or license. You can edit this file manually, or use -commands like `uv add` and `uv remove` to manage your project through the -CLI. +This is where you specify dependencies, as well as details about the project such as it's +description or license. You can edit this file manually, or use commands like `uv add` and `uv +remove` to manage your project through the CLI. !!! tip @@ -75,34 +74,31 @@ CLI. ### `.venv` -The `.venv` folder contains your project's virtual environment, a Python -environment that is isolated from the rest of your system. This is where uv will -install your project's dependencies. +The `.venv` folder contains your project's virtual environment, a Python environment that is +isolated from the rest of your system. This is where uv will install your project's dependencies. ### `uv.lock` -`uv.lock` is a cross-platform 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 virtual environment. This file should be checked into version -control, allowing for consistent and reproducible installations across machines. +`uv.lock` is a cross-platform 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 virtual +environment. This file should be checked into version control, allowing for consistent and +reproducible installations across machines. -`uv.lock` is a human-readable TOML file but is managed by uv and should not be -edited manually. +`uv.lock` is a human-readable TOML file but is managed by uv and should not be edited manually. ## Running commands -`uv run` can be used to run arbitrary scripts or commands in your project -environment. This ensures that the lockfile and virtual environment are -up-to-date before executing a given command: +`uv run` can be used to run arbitrary scripts or commands in your project environment. This ensures +that the lockfile and virtual environment are up-to-date before executing a given command: ```console $ uv run python my_script.py $ uv run flask run -p 3000 ``` -Alternatively, you can use `uv sync` to manually synchronize the lockfile and -virtual environment before executing a command: +Alternatively, you can use `uv sync` to manually synchronize the lockfile and virtual environment +before executing a command: ```console $ uv sync @@ -116,8 +112,8 @@ $ python my_script.py ## Managing dependencies -You can add dependencies to your `pyproject.toml` with the `uv add` command. -This will also update the lockfile and virtual environment: +You can add dependencies to your `pyproject.toml` with the `uv add` command. This will also update +the lockfile and virtual environment: ```console $ uv add requests @@ -141,5 +137,4 @@ $ uv remove requests ## Next steps -See the [projects concept](../concepts/projects.md) documentation for more details about -projects. +See the [projects concept](../concepts/projects.md) documentation for more details about projects. diff --git a/docs/guides/scripts.md b/docs/guides/scripts.md index 6a8ba0d988dc..62776e4ad98c 100644 --- a/docs/guides/scripts.md +++ b/docs/guides/scripts.md @@ -1,7 +1,8 @@ # Running scripts -A Python script is a file intended for standalone execution, e.g., with `python