Fix and improve docs (#13620)

<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:

- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->

## Summary

I follow the advices from the IDE spell checker and grammar checker, fix
some typos, and improve the docs.
This commit is contained in:
Lan, Jian 2025-06-11 02:15:38 +08:00 committed by GitHub
parent f20a25f91f
commit 90a7208a73
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
15 changed files with 27 additions and 26 deletions

View file

@ -124,7 +124,7 @@ with the default build system.
Build systems are used to power the following features: Build systems are used to power the following features:
- Including or excluding files from distributions - Including or excluding files from distributions
- Editable install behavior - Editable installation behavior
- Dynamic project metadata - Dynamic project metadata
- Compilation of native code - Compilation of native code
- Vendoring shared libraries - Vendoring shared libraries

View file

@ -202,7 +202,7 @@ while building a Docker image. `uv sync` has several flags for this purpose.
- `--no-install-workspace`: Do not install any workspace members, including the root project - `--no-install-workspace`: Do not install any workspace members, including the root project
- `--no-install-package <NO_INSTALL_PACKAGE>`: Do not install the given package(s) - `--no-install-package <NO_INSTALL_PACKAGE>`: Do not install the given package(s)
When these options are used, all of the dependencies of the target are still installed. For example, When these options are used, all the dependencies of the target are still installed. For example,
`--no-install-project` will omit the _project_ but not any of its dependencies. `--no-install-project` will omit the _project_ but not any of its dependencies.
If used improperly, these flags can result in a broken environment since a package can be missing If used improperly, these flags can result in a broken environment since a package can be missing

View file

@ -50,7 +50,7 @@ the workspace context.
Every workspace needs a root, which is _also_ a workspace member. In the above example, `albatross` Every workspace needs a root, which is _also_ a workspace member. In the above example, `albatross`
is the workspace root, and the workspace members include all projects under the `packages` is the workspace root, and the workspace members include all projects under the `packages`
directory, with the exception of `seeds`. directory, except `seeds`.
By default, `uv run` and `uv sync` operates on the workspace root. For example, in the above By default, `uv run` and `uv sync` operates on the workspace root. For example, in the above
example, `uv run` and `uv run --package albatross` would be equivalent, while example, `uv run` and `uv run --package albatross` would be equivalent, while

View file

@ -64,8 +64,8 @@ A global `.python-version` file can be created in the user configuration directo
Discovery of `.python-version` files can be disabled with `--no-config`. Discovery of `.python-version` files can be disabled with `--no-config`.
uv will not search for `.python-version` files beyond project or workspace boundaries (with the uv will not search for `.python-version` files beyond project or workspace boundaries (except the
exception of the user configuration directory). user configuration directory).
## Installing a Python version ## Installing a Python version
@ -106,13 +106,13 @@ To install a specific implementation:
$ uv python install pypy $ uv python install pypy
``` ```
All of the [Python version request](#requesting-a-version) formats are supported except those that All the [Python version request](#requesting-a-version) formats are supported except those that are
are used for requesting local interpreters such as a file path. used for requesting local interpreters such as a file path.
By default `uv python install` will verify that a managed Python version is installed or install the By default `uv python install` will verify that a managed Python version is installed or install the
latest version. If a `.python-version` file is present, uv will install the Python version listed in latest version. If a `.python-version` file is present, uv will install the Python version listed in
the file. A project that requires multiple Python versions may define a `.python-versions` file. If the file. A project that requires multiple Python versions may define a `.python-versions` file. If
present, uv will install all of the Python versions listed in the file. present, uv will install all the Python versions listed in the file.
!!! important !!! important
@ -341,7 +341,7 @@ The implementations may be requested with either the long or short name:
- PyPy: `pypy`, `pp` - PyPy: `pypy`, `pp`
- GraalPy: `graalpy`, `gp` - GraalPy: `graalpy`, `gp`
Implementation name requests are not case sensitive. Implementation name requests are not case-sensitive.
See the [Python version request](#requesting-a-version) documentation for more details on the See the [Python version request](#requesting-a-version) documentation for more details on the
supported formats. supported formats.

View file

@ -300,7 +300,7 @@ If dependency resolution fails due to a transitive pre-release, uv will prompt u
Alternatively, the transitive dependency can be added as a [constraint](#dependency-constraints) or Alternatively, the transitive dependency can be added as a [constraint](#dependency-constraints) or
direct dependency (i.e. in `requirements.in` or `pyproject.toml`) with a pre-release version direct dependency (i.e. in `requirements.in` or `pyproject.toml`) with a pre-release version
specifier (e.g., `flask>=2.0.0rc1`) to opt-in to pre-release support for that specific dependency. specifier (e.g., `flask>=2.0.0rc1`) to opt in to pre-release support for that specific dependency.
Pre-releases are Pre-releases are
[notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to [notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to

View file

@ -256,7 +256,7 @@ For details, see the
### Workspace support ### Workspace support
If a project includes local dependencies (e.g., via If a project includes local dependencies (e.g., via
[Workspaces](../../concepts/projects/workspaces.md), those too must be included in the deployment [Workspaces](../../concepts/projects/workspaces.md)), those too must be included in the deployment
package. package.
We'll start by extending the above example to include a dependency on a locally-developed library We'll start by extending the above example to include a dependency on a locally-developed library

View file

@ -530,7 +530,7 @@ REPO PREDICATE_TYPE WORKFLOW
astral-sh/uv https://slsa.dev/provenance/v1 .github/workflows/build-docker.yml@refs/heads/main astral-sh/uv https://slsa.dev/provenance/v1 .github/workflows/build-docker.yml@refs/heads/main
``` ```
This tells you that the specific Docker image was built by the official uv Github release workflow This tells you that the specific Docker image was built by the official uv GitHub release workflow
and hasn't been tampered with since. and hasn't been tampered with since.
GitHub attestations build on the [sigstore.dev infrastructure](https://www.sigstore.dev/). As such GitHub attestations build on the [sigstore.dev infrastructure](https://www.sigstore.dev/). As such

View file

@ -93,7 +93,7 @@ explicit = true
Even though `uv publish` retries failed uploads, it can happen that publishing fails in the middle, Even though `uv publish` retries failed uploads, it can happen that publishing fails in the middle,
with some files uploaded and some files still missing. With PyPI, you can retry the exact same with some files uploaded and some files still missing. With PyPI, you can retry the exact same
command, existing identical files will be ignored. With other registries, use command, existing identical files will be ignored. With other registries, use
`--check-url <index url>` with the index URL (not the publish URL) the packages belong to. When `--check-url <index url>` with the index URL (not the publishing URL) the packages belong to. When
using `--index`, the index URL is used as check URL. uv will skip uploading files that are identical using `--index`, the index URL is used as check URL. uv will skip uploading files that are identical
to files in the registry, and it will also handle raced parallel uploads. Note that existing files to files in the registry, and it will also handle raced parallel uploads. Note that existing files
need to match exactly with those previously uploaded to the registry, this avoids accidentally need to match exactly with those previously uploaded to the registry, this avoids accidentally

View file

@ -239,7 +239,7 @@ $ uv tool upgrade --all
## Requesting Python versions ## Requesting Python versions
By default, uv will use your default Python interpreter (the first it finds) when when running, By default, uv will use your default Python interpreter (the first it finds) when running,
installing, or upgrading tools. You can specify the Python interpreter to use with the `--python` installing, or upgrading tools. You can specify the Python interpreter to use with the `--python`
option. option.
@ -262,7 +262,7 @@ $ uv tool upgrade --python 3.10 ruff
``` ```
For more details on requesting Python versions, see the For more details on requesting Python versions, see the
[Python version](../concepts/python-versions.md#requesting-a-version) concept page.. [Python version](../concepts/python-versions.md#requesting-a-version) concept page.
## Legacy Windows Scripts ## Legacy Windows Scripts

View file

@ -400,7 +400,7 @@ the `subprocess` option is supported.
Unlike `pip`, uv does not enable keyring authentication by default. Unlike `pip`, uv does not enable keyring authentication by default.
Unlike `pip`, uv does not wait until a request returns a HTTP 401 before searching for Unlike `pip`, uv does not wait until a request returns an HTTP 401 before searching for
authentication. uv attaches authentication to all requests for hosts with credentials available. authentication. uv attaches authentication to all requests for hosts with credentials available.
## `egg` support ## `egg` support

View file

@ -2,7 +2,7 @@
## Listing installed packages ## Listing installed packages
To list all of the packages in the environment: To list all the packages in the environment:
```console ```console
$ uv pip list $ uv pip list
@ -14,7 +14,7 @@ To list the packages in a JSON format:
$ uv pip list --format json $ uv pip list --format json
``` ```
To list all of the packages in the environment in a `requirements.txt` format: To list all the packages in the environment in a `requirements.txt` format:
```console ```console
$ uv pip freeze $ uv pip freeze

View file

@ -1,6 +1,6 @@
# The uv installer # The uv installer
## Changing the install path ## Changing the installation path
By default, uv is installed to `~/.local/bin`. If `XDG_BIN_HOME` is set, it will be used instead. By default, uv is installed to `~/.local/bin`. If `XDG_BIN_HOME` is set, it will be used instead.
Similarly, if `XDG_DATA_HOME` is set, the target directory will be inferred as Similarly, if `XDG_DATA_HOME` is set, the target directory will be inferred as
@ -43,10 +43,11 @@ $ curl -LsSf https://astral.sh/uv/install.sh | env UV_UNMANAGED_INSTALL="/custom
The use of `UV_UNMANAGED_INSTALL` will also disable self-updates (via `uv self update`). The use of `UV_UNMANAGED_INSTALL` will also disable self-updates (via `uv self update`).
## Passing options to the install script ## Passing options to the installation script
Using environment variables is recommended because they are consistent across platforms. However, Using environment variables is recommended because they are consistent across platforms. However,
options can be passed directly to the install script. For example, to see the available options: options can be passed directly to the installation script. For example, to see the available
options:
```console ```console
$ curl -LsSf https://astral.sh/uv/install.sh | sh -s -- --help $ curl -LsSf https://astral.sh/uv/install.sh | sh -s -- --help

View file

@ -3371,7 +3371,7 @@ must either be pinned to exact versions (e.g., `==1.0.0`), or be specified via d
Hash-checking mode introduces a number of additional constraints: Hash-checking mode introduces a number of additional constraints:
- Git dependencies are not supported. - Git dependencies are not supported.
- Editable installs are not supported. - Editable installations are not supported.
- Local dependencies are not supported, unless they point to a specific wheel (`.whl`) or - Local dependencies are not supported, unless they point to a specific wheel (`.whl`) or
source archive (`.zip`, `.tar.gz`), as opposed to a directory. source archive (`.zip`, `.tar.gz`), as opposed to a directory.

View file

@ -105,7 +105,7 @@ wheel exists in the index, uv tries to build the source distribution.
You can check which wheels exist for a PyPI project under “Download Files”, e.g. You can check which wheels exist for a PyPI project under “Download Files”, e.g.
https://pypi.org/project/numpy/2.1.1.md#files. Wheels with `...-py3-none-any.whl` filenames work https://pypi.org/project/numpy/2.1.1.md#files. Wheels with `...-py3-none-any.whl` filenames work
everywhere, others have the operating system and platform in the filename. In the linked `numpy` everywhere, others have the operating system and platform in the filename. In the linked `numpy`
example, you can see that there are pre-built distributions for Python 3.10 to 3.13 on MacOS, Linux example, you can see that there are pre-built distributions for Python 3.10 to 3.13 on macOS, Linux
and Windows. and Windows.
## Common build failures ## Common build failures

View file

@ -9,7 +9,7 @@ a maintainer much longer to identify the root cause of the problem.
## How to write a reproducible example ## How to write a reproducible example
When writing a reproducible example, the goal is to provide all of the context necessary for someone When writing a reproducible example, the goal is to provide all the context necessary for someone
else to reproduce your example. This includes: else to reproduce your example. This includes:
- The platform you're using (e.g., the operating system and architecture) - The platform you're using (e.g., the operating system and architecture)
@ -124,8 +124,8 @@ In addition to the script, include _verbose_ logs (i.e., with the `-v` flag) of
complete error message. complete error message.
Whenever a script relies on external state, be sure to share that information. For example, if you Whenever a script relies on external state, be sure to share that information. For example, if you
wrote the script on Windows and it uses a Python version that you installed with `choco` and runs on wrote the script on Windows, and it uses a Python version that you installed with `choco` and runs
PowerShell 6.2, please include that in the report. on PowerShell 6.2, please include that in the report.
### Git repository ### Git repository