mirror of
https://github.com/astral-sh/uv.git
synced 2025-07-07 13:25: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:
|
||||
|
||||
- Including or excluding files from distributions
|
||||
- Editable install behavior
|
||||
- Editable installation behavior
|
||||
- Dynamic project metadata
|
||||
- Compilation of native code
|
||||
- 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-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.
|
||||
|
||||
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`
|
||||
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
|
||||
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`.
|
||||
|
||||
uv will not search for `.python-version` files beyond project or workspace boundaries (with the
|
||||
exception of the user configuration directory).
|
||||
uv will not search for `.python-version` files beyond project or workspace boundaries (except the
|
||||
user configuration directory).
|
||||
|
||||
## Installing a Python version
|
||||
|
||||
|
@ -106,13 +106,13 @@ To install a specific implementation:
|
|||
$ uv python install pypy
|
||||
```
|
||||
|
||||
All of the [Python version request](#requesting-a-version) formats are supported except those that
|
||||
are used for requesting local interpreters such as a file path.
|
||||
All the [Python version request](#requesting-a-version) formats are supported except those that are
|
||||
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
|
||||
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
|
||||
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
|
||||
|
||||
|
@ -341,7 +341,7 @@ The implementations may be requested with either the long or short name:
|
|||
- PyPy: `pypy`, `pp`
|
||||
- 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
|
||||
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
|
||||
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
|
||||
[notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to
|
||||
|
|
|
@ -256,7 +256,7 @@ For details, see the
|
|||
### Workspace support
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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,
|
||||
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
|
||||
`--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
|
||||
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
|
||||
|
|
|
@ -239,7 +239,7 @@ $ uv tool upgrade --all
|
|||
|
||||
## 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`
|
||||
option.
|
||||
|
||||
|
@ -262,7 +262,7 @@ $ uv tool upgrade --python 3.10 ruff
|
|||
```
|
||||
|
||||
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
|
||||
|
||||
|
|
|
@ -400,7 +400,7 @@ the `subprocess` option is supported.
|
|||
|
||||
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.
|
||||
|
||||
## `egg` support
|
||||
|
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
## Listing installed packages
|
||||
|
||||
To list all of the packages in the environment:
|
||||
To list all the packages in the environment:
|
||||
|
||||
```console
|
||||
$ uv pip list
|
||||
|
@ -14,7 +14,7 @@ To list the packages in a JSON format:
|
|||
$ 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
|
||||
$ uv pip freeze
|
||||
|
|
|
@ -1,6 +1,6 @@
|
|||
# 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.
|
||||
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`).
|
||||
|
||||
## Passing options to the install script
|
||||
## Passing options to the installation script
|
||||
|
||||
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
|
||||
$ 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:
|
||||
|
||||
- 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
|
||||
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.
|
||||
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`
|
||||
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.
|
||||
|
||||
## 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
|
||||
|
||||
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:
|
||||
|
||||
- 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.
|
||||
|
||||
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
|
||||
PowerShell 6.2, please include that in the report.
|
||||
wrote the script on Windows, and it uses a Python version that you installed with `choco` and runs
|
||||
on PowerShell 6.2, please include that in the report.
|
||||
|
||||
### Git repository
|
||||
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue