mirror of
https://github.com/astral-sh/uv.git
synced 2025-07-07 21:35:00 +00:00
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:
parent
f20a25f91f
commit
90a7208a73
15 changed files with 27 additions and 26 deletions
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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.
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue