mirror of
https://github.com/astral-sh/uv.git
synced 2025-07-07 13:25:00 +00:00
Restructure documentation sections to focus on new user experience (#4586)
Moving the preview features to top-level concepts and pushing the
pip-compatible interface down.
e.g.
<img width="291" alt="Screenshot 2024-06-27 at 7 03 48 AM"
src="500ad97d
-899d-4051-b59d-e74786b3a45f">
This commit is contained in:
parent
d05bb45c74
commit
12e12d066d
10 changed files with 69 additions and 63 deletions
|
@ -7,17 +7,20 @@
|
||||||
- [Installing uv](installation.md)
|
- [Installing uv](installation.md)
|
||||||
- [First steps](first-steps.md)
|
- [First steps](first-steps.md)
|
||||||
|
|
||||||
# Basic concepts
|
# Guides
|
||||||
|
|
||||||
- [Python environments](pip/environments.md)
|
- [Installing Python](guides/install-python.md)
|
||||||
- [Managing packages](pip/packages.md)
|
- [Running scripts](guides/scripts.md)
|
||||||
- [Inspecting packages](pip/inspection.md)
|
- [Installing tools](guides/tools.md)
|
||||||
- [Declaring dependencies](pip/dependencies.md)
|
- [Creating a project](guides/projects.md)
|
||||||
- [Locking environments](pip/compile.md)
|
|
||||||
|
|
||||||
# Advanced concepts
|
# Concepts
|
||||||
|
|
||||||
- [Python discovery](python/discovery.md)
|
- [Projects](preview/projects.md)
|
||||||
|
- [Command-line tools](preview/tools.md)
|
||||||
|
- [Python toolchains](preview/toolchains.md)
|
||||||
|
- [Workspaces](preview/workspaces.md)
|
||||||
|
- [Dependency sources](preview/dependencies.md)
|
||||||
- [Resolution](resolution.md)
|
- [Resolution](resolution.md)
|
||||||
- [Caching](cache.md)
|
- [Caching](cache.md)
|
||||||
- [Authentication](configuration/authentication.md)
|
- [Authentication](configuration/authentication.md)
|
||||||
|
@ -33,14 +36,13 @@
|
||||||
- [Using in GitHub Actions](guides/github.md)
|
- [Using in GitHub Actions](guides/github.md)
|
||||||
- [Using in pre-commit](guides/pre-commit.md)
|
- [Using in pre-commit](guides/pre-commit.md)
|
||||||
|
|
||||||
# Preview features
|
# Low-level operations
|
||||||
|
|
||||||
- [Introduction](preview/introduction.md)
|
- [Using environments](pip/environments.md)
|
||||||
- [Projects](preview/projects.md)
|
- [Managing packages](pip/packages.md)
|
||||||
- [Dependency specification](preview/dependencies.md)
|
- [Inspecting packages](pip/inspection.md)
|
||||||
- [Workspaces](preview/workspaces.md)
|
- [Declaring dependencies](pip/dependencies.md)
|
||||||
- [Command-line tools](preview/tools.md)
|
- [Locking environments](pip/compile.md)
|
||||||
- [Python toolchains](preview/toolchains.md)
|
|
||||||
|
|
||||||
# Policies
|
# Policies
|
||||||
|
|
||||||
|
|
1
docs/guides/install-python.md
Normal file
1
docs/guides/install-python.md
Normal file
|
@ -0,0 +1 @@
|
||||||
|
# Installing Python
|
1
docs/guides/project.md
Normal file
1
docs/guides/project.md
Normal file
|
@ -0,0 +1 @@
|
||||||
|
# Creating a project
|
1
docs/guides/projects.md
Normal file
1
docs/guides/projects.md
Normal file
|
@ -0,0 +1 @@
|
||||||
|
# Creating a project
|
1
docs/guides/scripts.md
Normal file
1
docs/guides/scripts.md
Normal file
|
@ -0,0 +1 @@
|
||||||
|
# Running a script
|
1
docs/guides/tools.md
Normal file
1
docs/guides/tools.md
Normal file
|
@ -0,0 +1 @@
|
||||||
|
# Installing tools
|
|
@ -87,3 +87,32 @@ If uv is installed in a Python environment, e.g., with `pip`, it can still be us
|
||||||
other environments. However, when invoked with `python -m uv`, uv will default to using the parent
|
other environments. However, when invoked with `python -m uv`, uv will default to using the parent
|
||||||
interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for
|
interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for
|
||||||
general usage.
|
general usage.
|
||||||
|
|
||||||
|
uv itself does not depend on Python, but it does need to locate a Python environment to (1)
|
||||||
|
install dependencies into the environment and (2) build source distributions.
|
||||||
|
|
||||||
|
## Discovery of Python environments
|
||||||
|
|
||||||
|
When running a command that mutates an environment such as `uv pip sync` or `uv pip install`,
|
||||||
|
uv will search for a virtual environment in the following order:
|
||||||
|
|
||||||
|
- An activated virtual environment based on the `VIRTUAL_ENV` environment variable.
|
||||||
|
- An activated Conda environment based on the `CONDA_PREFIX` environment variable.
|
||||||
|
- A virtual environment at `.venv` in the current directory, or in the nearest parent directory.
|
||||||
|
|
||||||
|
If no virtual environment is found, uv will prompt the user to create one in the current
|
||||||
|
directory via `uv venv`.
|
||||||
|
|
||||||
|
If the `--system` flag is included, uv will skip virtual environments and search for:
|
||||||
|
|
||||||
|
- The Python interpreter available as `python3` on macOS and Linux, or `python.exe` on Windows.
|
||||||
|
- 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:
|
||||||
|
|
||||||
|
- The Python interpreter available as, e.g., `python3.7` on macOS and Linux.
|
||||||
|
|
||||||
|
When running a command that does not mutate the environment such as `uv pip compile`, uv does not
|
||||||
|
_require_ a virtual environment. Instead, it needs a Python toolchain to create ephemeral environments.
|
||||||
|
See the documentation on [toolchain discovery](./preview/toolchains.md#discovery-order) for details on discovery.
|
||||||
|
|
|
@ -115,3 +115,16 @@ However, It's possible to adjust uv's toolchain selection preference with the `t
|
||||||
- `only-system`: Only use system toolchains, never use managed toolchains.
|
- `only-system`: Only use system toolchains, never use managed toolchains.
|
||||||
|
|
||||||
These options allow disabling uv's managed toolchains entirely or always using them and ignoring any existing system installations.
|
These options allow disabling uv's managed toolchains entirely or always using them and ignoring any existing system installations.
|
||||||
|
|
||||||
|
## Discovery order
|
||||||
|
|
||||||
|
When searching for a toolchain, the following locations are checked:
|
||||||
|
|
||||||
|
- Managed toolchains in the `UV_TOOLCHAIN_DIR`.
|
||||||
|
- A Python interpreter on the `PATH` as `python3` on macOS and Linux, or `python.exe` on Windows.
|
||||||
|
- 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:
|
||||||
|
|
||||||
|
- A Python interpreter on the `PATH` as, e.g., `python3.7` on macOS and Linux.
|
||||||
|
|
|
@ -1,45 +0,0 @@
|
||||||
# Python discovery
|
|
||||||
|
|
||||||
uv itself does not depend on Python, but it does need to locate a Python environment to (1)
|
|
||||||
install dependencies into the environment and (2) build source distributions.
|
|
||||||
|
|
||||||
## Environment mutating commands
|
|
||||||
|
|
||||||
When running a command that mutates an environment such as `uv pip sync` or `uv pip install`,
|
|
||||||
uv will search for a virtual environment in the following order:
|
|
||||||
|
|
||||||
- An activated virtual environment based on the `VIRTUAL_ENV` environment variable.
|
|
||||||
- An activated Conda environment based on the `CONDA_PREFIX` environment variable.
|
|
||||||
- A virtual environment at `.venv` in the current directory, or in the nearest parent directory.
|
|
||||||
|
|
||||||
If no virtual environment is found, uv will prompt the user to create one in the current
|
|
||||||
directory via `uv venv`.
|
|
||||||
|
|
||||||
If the `--system` flag is included, uv will skip virtual environments and search for:
|
|
||||||
|
|
||||||
- The Python interpreter available as `python3` on macOS and Linux, or `python.exe` on Windows.
|
|
||||||
- On Windows, the Python interpreter returned by `py --list-paths` that matches the requested
|
|
||||||
version.
|
|
||||||
|
|
||||||
## Commands that need an interpreter
|
|
||||||
|
|
||||||
When running a command that needs an interpreter but does not mutate the environment such as `uv pip compile`,
|
|
||||||
uv does not _require_ a virtual environment and will search for a Python interpreter in the following order:
|
|
||||||
|
|
||||||
- An activated virtual environment based on the `VIRTUAL_ENV` environment variable.
|
|
||||||
- An activated Conda environment based on the `CONDA_PREFIX` environment variable.
|
|
||||||
- A virtual environment at `.venv` in the current directory, or in the nearest parent directory.
|
|
||||||
- The Python interpreter available as `python3` on macOS and Linux, or `python.exe` on Windows.
|
|
||||||
|
|
||||||
If a `--python-version` is provided to `uv pip compile` (e.g., `--python-version=3.7`), uv will
|
|
||||||
search for a Python interpreter matching that version in the following order:
|
|
||||||
|
|
||||||
- An activated virtual environment based on the `VIRTUAL_ENV` environment variable.
|
|
||||||
- An activated Conda environment based on the `CONDA_PREFIX` environment variable.
|
|
||||||
- A virtual environment at `.venv` in the current directory, or in the nearest parent directory.
|
|
||||||
- The Python interpreter available as, e.g., `python3.7` on macOS and Linux.
|
|
||||||
- The Python interpreter available as `python3` on macOS and Linux, or `python.exe` on Windows.
|
|
||||||
- On Windows, the Python interpreter returned by `py --list-paths` that matches the requested
|
|
||||||
version.
|
|
||||||
|
|
||||||
These commands may create ephemeral virtual environments with the interpreter.
|
|
|
@ -12,15 +12,17 @@ html {
|
||||||
}
|
}
|
||||||
.chapter li.chapter-item {
|
.chapter li.chapter-item {
|
||||||
margin-left: 1em;
|
margin-left: 1em;
|
||||||
margin-block-start: 0.3em;
|
margin-block-start: 0.2em;
|
||||||
font-weight: 300;
|
font-weight: 300;
|
||||||
margin-block-end: 0.5em
|
margin-block-end: 0.4em;
|
||||||
|
line-height: 1.2em;
|
||||||
|
font-size: 1.05em;
|
||||||
}
|
}
|
||||||
.chapter li.chapter-item a:hover {
|
.chapter li.chapter-item a:hover {
|
||||||
text-decoration: underline;
|
text-decoration: underline;
|
||||||
}
|
}
|
||||||
.chapter li.part-title {
|
.chapter li.part-title {
|
||||||
margin: 10px 0 0px 0;
|
margin: 0 0 0 0;
|
||||||
font-weight: 500;
|
font-weight: 500;
|
||||||
font-size: 1.3em;
|
font-size: 1.3em;
|
||||||
}
|
}
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue