diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 4df45b37f..7abbe0ea4 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -7,17 +7,20 @@ - [Installing uv](installation.md) - [First steps](first-steps.md) -# Basic concepts +# Guides -- [Python environments](pip/environments.md) -- [Managing packages](pip/packages.md) -- [Inspecting packages](pip/inspection.md) -- [Declaring dependencies](pip/dependencies.md) -- [Locking environments](pip/compile.md) +- [Installing Python](guides/install-python.md) +- [Running scripts](guides/scripts.md) +- [Installing tools](guides/tools.md) +- [Creating a project](guides/projects.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) - [Caching](cache.md) - [Authentication](configuration/authentication.md) @@ -33,14 +36,13 @@ - [Using in GitHub Actions](guides/github.md) - [Using in pre-commit](guides/pre-commit.md) -# Preview features +# Low-level operations -- [Introduction](preview/introduction.md) -- [Projects](preview/projects.md) -- [Dependency specification](preview/dependencies.md) -- [Workspaces](preview/workspaces.md) -- [Command-line tools](preview/tools.md) -- [Python toolchains](preview/toolchains.md) +- [Using environments](pip/environments.md) +- [Managing packages](pip/packages.md) +- [Inspecting packages](pip/inspection.md) +- [Declaring dependencies](pip/dependencies.md) +- [Locking environments](pip/compile.md) # Policies diff --git a/docs/guides/install-python.md b/docs/guides/install-python.md new file mode 100644 index 000000000..aa0f171a7 --- /dev/null +++ b/docs/guides/install-python.md @@ -0,0 +1 @@ +# Installing Python diff --git a/docs/guides/project.md b/docs/guides/project.md new file mode 100644 index 000000000..55a2a2e32 --- /dev/null +++ b/docs/guides/project.md @@ -0,0 +1 @@ +# Creating a project diff --git a/docs/guides/projects.md b/docs/guides/projects.md new file mode 100644 index 000000000..55a2a2e32 --- /dev/null +++ b/docs/guides/projects.md @@ -0,0 +1 @@ +# Creating a project diff --git a/docs/guides/scripts.md b/docs/guides/scripts.md new file mode 100644 index 000000000..dcba78666 --- /dev/null +++ b/docs/guides/scripts.md @@ -0,0 +1 @@ +# Running a script diff --git a/docs/guides/tools.md b/docs/guides/tools.md new file mode 100644 index 000000000..01e2a10e9 --- /dev/null +++ b/docs/guides/tools.md @@ -0,0 +1 @@ +# Installing tools diff --git a/docs/pip/environments.md b/docs/pip/environments.md index c3c2b232b..10a5cac8d 100644 --- a/docs/pip/environments.md +++ b/docs/pip/environments.md @@ -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 interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for 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. diff --git a/docs/preview/toolchains.md b/docs/preview/toolchains.md index 97ecee2a2..ba0e7c7ff 100644 --- a/docs/preview/toolchains.md +++ b/docs/preview/toolchains.md @@ -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. 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. diff --git a/docs/python/discovery.md b/docs/python/discovery.md deleted file mode 100644 index c0a7d0710..000000000 --- a/docs/python/discovery.md +++ /dev/null @@ -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. diff --git a/docs/style.css b/docs/style.css index 9834d4d44..9e734c07a 100644 --- a/docs/style.css +++ b/docs/style.css @@ -12,15 +12,17 @@ html { } .chapter li.chapter-item { margin-left: 1em; - margin-block-start: 0.3em; + margin-block-start: 0.2em; 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 { text-decoration: underline; } .chapter li.part-title { - margin: 10px 0 0px 0; + margin: 0 0 0 0; font-weight: 500; font-size: 1.3em; }