diff --git a/docs/cache.md b/docs/concepts/cache.md similarity index 100% rename from docs/cache.md rename to docs/concepts/cache.md diff --git a/docs/dependencies.md b/docs/concepts/dependencies.md similarity index 100% rename from docs/dependencies.md rename to docs/concepts/dependencies.md diff --git a/docs/concepts/index.md b/docs/concepts/index.md new file mode 100644 index 000000000..5e3a02a74 --- /dev/null +++ b/docs/concepts/index.md @@ -0,0 +1,13 @@ +# Concepts overview + +Read the concept documents to learn more about uv's features: + +- [Projects](./projects.md) +- [Dependencies](./dependencies.md) +- [Workspaces](./workspaces.md) +- [Tools](./tools.md) +- [Python versions](./python-versions.md) +- [Resolution](./resolution.md) +- [Caching](./cache.md) + +Looking for a quick introduction to features? See the [guides](../guides/index.md) instead. diff --git a/docs/projects.md b/docs/concepts/projects.md similarity index 96% rename from docs/projects.md rename to docs/concepts/projects.md index 3eecd08fc..9f55e4b3d 100644 --- a/docs/projects.md +++ b/docs/concepts/projects.md @@ -4,7 +4,7 @@ Python projects are help manage Python applications spanning multiple files. !!! tip - Looking for an introduction to creating a project with uv? See the [projects guide](./guides/projects.md) first. + Looking for an introduction to creating a project with uv? See the [projects guide](../guides/projects.md) first. ## Project metadata @@ -44,7 +44,7 @@ To run a command in the project environment, use `uv run`. Alternatively the pro When `uv run` is invoked, it will create the project environment if it does not exist yet or ensure it is up to date if it exists. The project environment can also be explicitly created with `uv sync`. -It is _not_ recommended to modify the project environment manually, e.g., with `uv pip install`. For project dependencies, use `uv add` to add a package to the environment. For one-off requirements, use [`uvx`](./guides/tools.md) or [`uv run --with`](#running-commands-with-additional-dependencies). +It is _not_ recommended to modify the project environment manually, e.g., with `uv pip install`. For project dependencies, use `uv add` to add a package to the environment. For one-off requirements, use [`uvx`](../guides/tools.md) or [`uv run --with`](#running-commands-with-additional-dependencies). ## Lock file @@ -150,7 +150,7 @@ The requested version will be respected regardless of the project's requirements ### Running scripts -Scripts that declare inline metadata are automatically executed in environments isolated from the project. See the [scripts guide](./guides/scripts.md#declaring-script-dependencies) for more details. +Scripts that declare inline metadata are automatically executed in environments isolated from the project. See the [scripts guide](../guides/scripts.md#declaring-script-dependencies) for more details. For example, given a script: diff --git a/docs/python-versions.md b/docs/concepts/python-versions.md similarity index 100% rename from docs/python-versions.md rename to docs/concepts/python-versions.md diff --git a/docs/resolution.md b/docs/concepts/resolution.md similarity index 97% rename from docs/resolution.md rename to docs/concepts/resolution.md index 2dae1e580..2be42ef14 100644 --- a/docs/resolution.md +++ b/docs/concepts/resolution.md @@ -80,7 +80,7 @@ to model, and are a frequent source of bugs in other packaging tools. uv's pre-r is _intentionally_ limited and _intentionally_ requires user opt-in for pre-releases, to ensure correctness. -For more, see ["Pre-release compatibility"](./pip/compatibility.md#pre-release-compatibility) +For more, see ["Pre-release compatibility"](../pip/compatibility.md#pre-release-compatibility) ## Dependency overrides @@ -116,7 +116,7 @@ architectures, and Python implementations. In universal mode, the current Python will be treated as a lower bound. For example, `--universal --python-version 3.7` would produce a universal resolution for Python 3.7 and later. -If using uv's [project](./guides/projects.md) interface, the machine agnostic resolution will be used +If using uv's [project](../guides/projects.md) interface, the machine agnostic resolution will be used automatically and a `uv.lock` file will be created. The lock file can also be created with an explicit `uv lock` invocation. diff --git a/docs/tools.md b/docs/concepts/tools.md similarity index 96% rename from docs/tools.md rename to docs/concepts/tools.md index cddf9d870..62f20ece1 100644 --- a/docs/tools.md +++ b/docs/concepts/tools.md @@ -4,7 +4,7 @@ Tools are Python packages that provide command-line interfaces. Tools can be inv !!! note - See the [tools guide](./guides/tools.md) for an introduction to working with the tools interface — this document discusses details of tool management. + See the [tools guide](../guides/tools.md) for an introduction to working with the tools interface — this document discusses details of tool management. ## Tool environments diff --git a/docs/workspaces.md b/docs/concepts/workspaces.md similarity index 100% rename from docs/workspaces.md rename to docs/concepts/workspaces.md diff --git a/docs/configuration/authentication.md b/docs/configuration/authentication.md index 897f28a7f..6bbfc1a91 100644 --- a/docs/configuration/authentication.md +++ b/docs/configuration/authentication.md @@ -67,6 +67,6 @@ system's trust store. If client certificate authentication (mTLS) is desired, set the `SSL_CLIENT_CERT` environment variable to the path of the PEM formatted file containing the certificate followed by the private key. -## Authentication with commercial package indexes +## Authentication with alternative package indexes -See the [commercial indexes integration guide](../guides/integration/commercial-indexes.md) for details on authentication with popular commercial Python package indexes. +See the [alternative indexes integration guide](../guides/integration/alternative-indexes.md) for details on authentication with popular alternative Python package indexes. diff --git a/docs/configuration/index.md b/docs/configuration/index.md new file mode 100644 index 000000000..ec3572c8a --- /dev/null +++ b/docs/configuration/index.md @@ -0,0 +1,11 @@ +# Configuration overview + +Read about the various ways to configure uv: + +- [Using configuration files](./files.md) +- [Using environment variables](./environment.md) +- [Configuring authentication](./authentication.md) + + + +Or, jump to the [settings reference](../settings.md) which enumerates the available configuration options. diff --git a/docs/features.md b/docs/features.md index 3aea458de..562d4dc39 100644 --- a/docs/features.md +++ b/docs/features.md @@ -51,7 +51,7 @@ Running and installing tools published to Python package indexes, e.g., `ruff` o See the [guide on tools](./guides/tools.md) to get started. -## Low-level +## The pip interface Manually managing environments and packages — intended to be used in legacy workflows or cases where the high-level commands do not provide enough control. diff --git a/docs/first-steps.md b/docs/first-steps.md index c5526d080..2344cc6bc 100644 --- a/docs/first-steps.md +++ b/docs/first-steps.md @@ -56,4 +56,4 @@ When using the long help menu, uv will attempt to use `less` or `more` to "page" ## Next steps -Now that you've confirmed uv is installed and know how to get help, check out an [overview of features](./features.md) or jump straight into the [guides](./guides/overview.md) to start using uv. +Now that you've confirmed uv is installed and know how to get help, check out an [overview of features](./features.md) or jump straight into the [guides](./guides/index.md) to start using uv. diff --git a/docs/guides/overview.md b/docs/guides/index.md similarity index 52% rename from docs/guides/overview.md rename to docs/guides/index.md index ab56bfe1f..1a96d15f2 100644 --- a/docs/guides/overview.md +++ b/docs/guides/index.md @@ -1,4 +1,4 @@ -# Overview +# Guides overview Check out one of the core guides to get started: @@ -12,15 +12,6 @@ Learn how to integrate uv with other software: - [Using in Docker images](./integration/docker.md) - [Using with pre-commit](./integration/pre-commit.md) - [Using in GitHub Actions](./integration/github.md) -- [Using with commercial package indexes](./integration/commercial-indexes.md) +- [Using with alternative package indexes](./integration/alternative-indexes.md) -Or, explore the concept documentation for comprehensive breakdown of each feature: - -- [Projects](../projects.md) -- [Dependencies](../dependencies.md) -- [Workspaces](../workspaces.md) -- [Tools](../tools.md) -- [Python versions](../python-versions.md) -- [Resolution](../resolution.md) -- [Caching](../cache.md) -- [Authentication](../configuration/authentication.md) +Or, explore the [concept documentation](../concepts/index.md) for comprehensive breakdown of each feature. diff --git a/docs/guides/install-python.md b/docs/guides/install-python.md index 171e677fd..da9b384ce 100644 --- a/docs/guides/install-python.md +++ b/docs/guides/install-python.md @@ -16,7 +16,7 @@ This will install a uv managed Python version even if there is already a Python !!! note - Python does not publish official distributable binaries so uv uses third-party distributions from the [`python-build-standalone`](https://github.com/indygreg/python-build-standalone) project. The project is partially maintained by the uv maintainers and is used by many other Python projects. See the [Python distributions](../python-versions.md#python-distributions) documentation for more details. + Python does not publish official distributable binaries so uv uses third-party distributions from the [`python-build-standalone`](https://github.com/indygreg/python-build-standalone) project. The project is partially maintained by the uv maintainers and is used by many other Python projects. See the [Python distributions](../concepts/python-versions.md#python-distributions) documentation for more details. @@ -75,6 +75,6 @@ Note that when an automatic Python installation occurs, the `python` command wil ## Using an existing Python installation -uv will also use an existing Python installation if already present on your system. There is no configuration necessary for this behavior: uv will use the system Python if it satisfies the requirements of the command invocation. See the [Python discovery](../python-versions.md#discovery-order) documentation for details. +uv will also use an existing Python installation if already present on your system. There is no configuration necessary for this behavior: uv will use the system Python if it satisfies the requirements of the command invocation. See the [Python discovery](../concepts/python-versions.md#discovery-order) documentation for details. -To force uv to use the system Python, provide the `--python-preference only-system` option. See the [Python version preference](../python-versions.md#adjusting-python-version-preferences) documentation for more details. +To force uv to use the system Python, provide the `--python-preference only-system` option. See the [Python version preference](../concepts/python-versions.md#adjusting-python-version-preferences) documentation for more details. diff --git a/docs/guides/integration/commercial-indexes.md b/docs/guides/integration/alternative-indexes.md similarity index 93% rename from docs/guides/integration/commercial-indexes.md rename to docs/guides/integration/alternative-indexes.md index 5fb8be544..c456fa2ea 100644 --- a/docs/guides/integration/commercial-indexes.md +++ b/docs/guides/integration/alternative-indexes.md @@ -1,6 +1,6 @@ -# Using uv commercial package indexes +# Using alternative package indexes -While uv uses the official Python Package Index (PyPI) by default, it also supports commercial package indexes. Most commercial indexes require various forms of authentication, which requires some initial setup. +While uv uses the official Python Package Index (PyPI) by default, it also supports alternative package indexes. Most alternative indexes require various forms of authentication, which requires some initial setup. ## Azure Artifacts diff --git a/docs/guides/integration/index.md b/docs/guides/integration/index.md new file mode 100644 index 000000000..01a20e77d --- /dev/null +++ b/docs/guides/integration/index.md @@ -0,0 +1,8 @@ +# Integration guides + +Learn how to integrate uv with other software: + +- [Using in Docker images](./docker.md) +- [Using with pre-commit](./pre-commit.md) +- [Using in GitHub Actions](./github.md) +- [Using an Azure Artifacts index](./alternative-indexes.md#azure-artifacts) diff --git a/docs/guides/projects.md b/docs/guides/projects.md index b906c7c07..4b0394219 100644 --- a/docs/guides/projects.md +++ b/docs/guides/projects.md @@ -141,5 +141,5 @@ $ uv remove requests ## Next steps -See the [projects concept](../projects.md) documentation for more details about +See the [projects concept](../concepts/projects.md) documentation for more details about projects. diff --git a/docs/guides/scripts.md b/docs/guides/scripts.md index 2358cca4a..6a8ba0d98 100644 --- a/docs/guides/scripts.md +++ b/docs/guides/scripts.md @@ -151,7 +151,7 @@ type Point = tuple[float, float] print(Point) ``` -uv will fetch the required Python version if it is not installed — see the documentation on [Python versions](../python-versions.md) for more details. Note that the `dependencies` field must be provided even if empty. +uv will fetch the required Python version if it is not installed — see the documentation on [Python versions](../concepts/python-versions.md) for more details. Note that the `dependencies` field must be provided even if empty. Note that when using inline script metadata, even if `uv run` is used in a _project_, the project's dependencies will be ignored. The `--isolated` flag is not required. @@ -177,4 +177,4 @@ $ uv run --python 3.10 example.py 3.10.13 ``` -See the [Python version request](../python-versions.md#requesting-a-version) documentation for more details on requesting Python versions. +See the [Python version request](../concepts/python-versions.md#requesting-a-version) documentation for more details on requesting Python versions. diff --git a/docs/guides/tools.md b/docs/guides/tools.md index aaa9997c0..9afc71c7f 100644 --- a/docs/guides/tools.md +++ b/docs/guides/tools.md @@ -142,4 +142,4 @@ $ uv tool install mkdocs --with mkdocs-material ## Next steps -See the [tools concept](../tools.md) documentation for more details on how tools are managed. +See the [tools concept](../concepts/tools.md) documentation for more details on how tools are managed. diff --git a/docs/index.md b/docs/index.md index 69a1ba405..c86d4b34a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,12 +25,12 @@ An extremely fast Python package and project manager, written in Rust. - 🐍 [Installs and manages](./guides/install-python.md) Python versions. - 🛠️ [Runs and installs](./guides/tools.md) Python applications. - ❇️ [Runs scripts](./guides/scripts.md), with support for [inline dependency metadata](./guides/scripts.md#declaring-script-dependencies). -- 🗂️ Provides [comprehensive project management](./guides/projects.md), with a [universal lockfile](./projects.md#lock-file). -- 🏢 Supports Cargo-style [workspaces](./workspaces.md) for scalable projects. +- 🗂️ Provides [comprehensive project management](./guides/projects.md), with a [universal lockfile](./concepts/projects.md#lock-file). +- 🏢 Supports Cargo-style [workspaces](./concepts/workspaces.md) for scalable projects. - 🚀 A replacement for `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `virtualenv`, and more. - ⚡️ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip` and `pip-tools` (`pip-compile` and `pip-sync`). -- 💾 Disk-space efficient, with a [global cache](./cache.md) for dependency deduplication. +- 💾 Disk-space efficient, with a [global cache](./concepts/cache.md) for dependency deduplication. - ⏬ Installable without Rust or Python via `curl` or `pip`. - 🖥️ Supports macOS, Linux, and Windows. @@ -157,7 +157,7 @@ Pinned `.python-version` to `pypy@3.11` See the [installing Python guide](./guides/install-python.md) to get started. -## Package management +## The pip interface uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands with support for a wide range of advanced `pip` features, including editable installs, Git dependencies, direct URL dependencies, local dependencies, constraints, source distributions, HTML and JSON indexes, and more. @@ -192,8 +192,8 @@ Installed 43 packages in 208ms ... ``` -See the [uv pip documentation](./pip/environments.md) to get started. +See the [uv pip documentation](./pip/index.md) to get started. ## Next steps -See the [first steps](./first-steps.md) or jump straight into the [guides](./guides/overview.md) to start using uv. +See the [first steps](./first-steps.md) or jump straight into the [guides](./guides/index.md) to start using uv. diff --git a/docs/pip/environments.md b/docs/pip/environments.md index 3d2cc870c..e0c5118b0 100644 --- a/docs/pip/environments.md +++ b/docs/pip/environments.md @@ -27,7 +27,7 @@ uv venv --python 3.11 Note this requires the requested Python version to be available on the system. However, if available, uv will download Python for you. -See the [Python version](../python-versions.md) documentation for more details. +See the [Python version](../concepts/python-versions.md) documentation for more details. ## Using a virtual environment @@ -115,4 +115,4 @@ If a specific Python version is requested, e.g., `--python 3.7`, additional exec 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](../python-versions.md#discovery-order) for details on discovery. +See the documentation on [toolchain discovery](../concepts/python-versions.md#discovery-order) for details on discovery. diff --git a/docs/pip/index.md b/docs/pip/index.md new file mode 100644 index 000000000..c471dfdc4 --- /dev/null +++ b/docs/pip/index.md @@ -0,0 +1,13 @@ +# The pip interface + +uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands. These commands work directly with the virtual environment, in contrast to uv's primary interfaces where the virtual environment is managed automatically. The `uv pip` interface exposes the speed and functionality of uv to power users and projects that are not ready to transition away from `pip` and `pip-tools`. + +The following sections discuss the basics of using `uv pip`: + +- [Creating and using environments](./environments.md) +- [Installing and managing packages](./packages.md) +- [Inspecting environments and packages](./inspection.md) +- [Declaring package dependencies](./dependencies.md) +- [Locking and syncing environments](./compile.md) + +Please note these commands do not _exactly_ implement the interfaces and behavior of the tools they are based on. The further you stray from common workflows, the more likely you are to encounter differences. Consult the [pip-compatibility guide](./compatibility.md) for details. diff --git a/mkdocs.template.yml b/mkdocs.template.yml index 5b1d90a28..5d87d156f 100644 --- a/mkdocs.template.yml +++ b/mkdocs.template.yml @@ -8,6 +8,7 @@ theme: - navigation.instant.prefetch - navigation.instant.progress - navigation.expand + - navigation.indexes - navigation.tracking - content.code.annotate - toc.follow @@ -75,30 +76,34 @@ nav: - First steps: first-steps.md - Features: features.md - Guides: - - Overview: guides/overview.md + - guides/index.md - Installing Python: guides/install-python.md - Running scripts: guides/scripts.md - Using tools: guides/tools.md - Working on projects: guides/projects.md - Concepts: - - Projects: projects.md - - Dependencies: dependencies.md - - Workspaces: workspaces.md - - Tools: tools.md - - Python versions: python-versions.md - - Resolution: resolution.md - - Caching: cache.md - - Authentication: configuration/authentication.md + - concepts/index.md + - Projects: concepts/projects.md + - Dependencies: concepts/dependencies.md + - Workspaces: concepts/workspaces.md + - Tools: concepts/tools.md + - Python versions: concepts/python-versions.md + - Resolution: concepts/resolution.md + - Caching: concepts/cache.md - Configuration: + - configuration/index.md - Configuration files: configuration/files.md - Environment variables: configuration/environment.md - Settings: settings.md + - Authentication: configuration/authentication.md - Integration guides: + - guides/integration/index.md - Docker: guides/integration/docker.md - GitHub Actions: guides/integration/github.md - Pre-commit: guides/integration/pre-commit.md - - Commercial indexes: guides/integration/commercial-indexes.md - - Low-level operations: + - Alternative indexes: guides/integration/alternative-indexes.md + - The pip interface: + - pip/index.md - Using environments: pip/environments.md - Managing packages: pip/packages.md - Inspecting packages: pip/inspection.md