Bundle of documentation changes (#5307)

Following #5239

docs/configuration/files.md

@@ -8,7 +8,7 @@ in the nearest parent directory.
 If a `pyproject.toml` file is found, uv will read configuration from the `[tool.uv.pip]` table.
 For example, to set a persistent index URL, add the following to a `pyproject.toml`:
 
-```toml
+```toml title="project.toml"
 [tool.uv.pip]
 index-url = "https://test.pypi.org/simple"
 ```
@@ -18,7 +18,7 @@ the directory hierarchy.)
 
 If a `uv.toml` file is found, uv will read from the `[pip]` table. For example:
 
-```toml
+```toml title="uv.toml"
 [pip]
 index-url = "https://test.pypi.org/simple"
 ```

docs/dependencies.md

@@ -19,7 +19,7 @@ standard.
 `project.dependencies` is structured as a list. Each entry includes a dependency name and
 version. An entry may include extras or environment markers for platform-specific packages. For example:
 
-```toml
+```toml title="pyproject.toml"
 [project]
 name = "albatross"
 version = "0.1.0"
@@ -37,41 +37,126 @@ dependencies = [
 ]
 ```
 
-If the project only requires packages from standaard package indexes, then `project.dependencies` is sufficient. If, the project depends on packages from Git, remote URLs, or local sources, `tool.uv.sources` is needed.
+If the project only requires packages from standard package indexes, then `project.dependencies` is sufficient. If, the project depends on packages from Git, remote URLs, or local sources, `tool.uv.sources` is needed.
 
 ## Dependency sources
 
-During development, the project may rely on a package that isn't available on PyPI. In the following example, the project will require several package sources:
+During development, the project may rely on a package that isn't available on PyPI. The following additional sources are supported by uv:
 
-- `tqdm` from a specific Git commit
+- Git
-- `importlib_metadata` from a dedicated URL
+- URL
-- `torch` from the PyTorch-specific index
+- Path
-- `mollymawk` from the current workspace
+- Workspace
 
-These requirements can be expressed by extending the definitions in the `project.dependencies` table with `tool.uv.sources` entries:
+Only a single source may be defined for each dependency.
 
-```toml
+Note that if a non-uv project uses a project with sources as a Git- or path-dependency, only
+`project.dependencies` is respected, the information in the source table
+will need to be re-specified in a format specific to the other package manager.
+
+### Git
+
+To add a Git dependency source, prefix a Git-compatible URL to clone with `git+`.
+
+For example:
+
+```console
+$ uv add git+https://github.com/encode/httpx
+```
+
+Will result in a `pyproject.toml` with:
+
+```toml title="pyproject.toml"
+[project]
+dependencies = [
+    "httpx",
+]
+
+[tool.uv.sources]
+httpx = { git = "https://github.com/encode/httpx" }
+```
+
+A revision, tag, or branch may also be included, e.g.:
+
+```console
+$ uv add git+https://github.com/encode/httpx --tag 0.27.0
+$ uv add git+https://github.com/encode/httpx --branch main
+$ uv add git+https://github.com/encode/httpx --rev 326b943
+```
+
+Git dependencies can also be manually added or edited in the `pyproject.toml` with the `{ git = <url> }` syntax. A target revision may be specified with one of: `rev`, `tag`, or `branch`. A `subdirectory` may be specified if the package isn't in the repository root.
+
+### URL
+
+To add a URL source, provide a `https://` URL to either a wheel (ending in `.whl`) or a source distribution (ending in `.zip` or `.tar.gz`).
+
+For example:
+
+```console
+$ uv add "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz"
+```
+
+Will result in a `pyproject.toml` with:
+
+```toml title="pyproject.toml"
+[project]
+dependencies = [
+    "httpx",
+]
+
+[tool.uv.sources]
+httpx = { url = "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz" }
+```
+
+URL dependencies can also be manually added or edited in the `pyproject.toml` with the `{ url = <url> }` syntax.  A `subdirectory` may be specified if the if the source distribution isn't in the archive root.
+
+### Path
+
+To add a path source, provide the path of a wheel (ending in `.whl`), a source distribution (ending in `.zip` or `.tar.gz`), or a directory containing a `pyproject.toml`.
+
+For example:
+
+```console
+$ uv add /example/foo.whl
+```
+
+Will result in a `pyproject.toml` with:
+
+```toml title="pyproject.toml"
+[project]
+dependencies = [
+    "foo",
+]
+
+[tool.uv.sources]
+foo = { path = "/example/foo.whl" }
+```
+
+The path may also be a relative path, e.g.:
+
+```console
+$ uv add ./foo
+```
+
+Note an [editable installation](#editables-dependencies) is not used for path dependencies. However, for directories, an editable installation may be requested, e.g.:
+
+```console
+$ uv add --editable ./foo
+```
+
+However, it is recommended to use [_workspaces_](#workspaces) instead of manual path dependencies. 
+
+### Workspace member
+
+To declare a workspace member, add the dependency with `{ workspace = true }`. All workspace members must be explicitly stated. Workspace members are [editable](#editables-dependencies) by default; `editable = false` may be included to install them as regular dependencies. See the [workspace](./workspaces.md) documentation for more details on workspaces.
+
+```toml title="pyproject.toml"
 [project]
-name = "albatross"
-version = "0.1.0"
 dependencies = [
-  # Any version in this range.
-  "tqdm >=4.66.2,<5",
-  # Exactly this version of torch.
-  "torch ==2.2.2",
-  # Install transformers with the torch extra.
-  "transformers[torch] >=4.39.3,<5",
-  # Only install this package on Python versions prior to 3.10.
-  "importlib_metadata >=7.1.0,<8; python_version < '3.10'",
   "mollymawk ==0.1.0"
 ]
 
 [tool.uv.sources]
-# Install a specific Git commit.
-tqdm = { git = "https://github.com/tqdm/tqdm", rev = "cc372d09dcd5a5eabdc6ed4cf365bdb0be004d44" }
-# Install a remote source distribution (`.zip`, `.tar.gz`) or wheel (`.whl`).
-importlib_metadata = { url = "https://github.com/python/importlib_metadata/archive/refs/tags/v7.1.0.zip" }
-# Use a package included in the same workspace (as an editable installation).
 mollymawk = { workspace = true }
 
 [tool.uv.workspace]
@@ -80,22 +165,6 @@ include = [
 ]
 ```
 
-uv supports the following sources:
-
-- **Git**: `git = <url>`. A git-compatible URL to clone. A target revision may be specified with one of: `rev`, `tag`, or `branch`. A `subdirectory` may be specified if the package isn't in the repository root.
-- **URL**: `url = <url>`. An `https://` URL to either a wheel (ending in `.whl`) or a source distribution
-  (ending in `.zip` or `.tar.gz`). A `subdirectory` may be specified if the if the source distribution isn't in the archive root.
-- **Path**: `path = <path>`. A path to a wheel (ending in `.whl`), a source
-  distribution (ending in `.zip` or `.tar.gz`), or a directory containing a `pyproject.toml`. 
-  The path may be absolute or relative path. It is recommended to use _workspaces_ instead of manual path dependencies. For directories, `editable = true` may be specified for an [editable](#editables-dependencies) installation.
-- **Workspace**: `workspace = true`. All workspace dependencies must be explicitly stated. Workspace dependencies are [editable](#editables-dependencies) by default; `editable = false` may be specified to install them as regular dependencies. See the [workspace](./workspaces.md) documentation for more details on workspaces.
-
-Only a single source may be defined for each dependency.
-
-Note that if a non-uv project uses this project as a Git- or path-dependency, only
-`project.dependencies` is respected, the information in the source table
-will need to be specified in a format specific to the other package manager.
-
 ## Optional dependencies
 
 It is common for projects that are published as libraries to make some features optional to reduce the default dependency tree. For example,
@@ -107,7 +176,7 @@ from extra name to its dependencies, following [PEP 508](#pep-508) syntax.
 
 Optional dependencies can have entries in `tool.uv.sources` the same as normal dependencies.
 
-```toml
+```toml title="pyproject.toml"
 [project]
 name = "pandas"
 version = "1.0.0"
@@ -126,19 +195,31 @@ excel = [
 ]
 ```
 
+To add an optional dependency, use the `--optional <extra>` option:
+
+```console
+$ uv add httpx --optional network
+```
+
 ## Development dependencies
 
 Unlike optional dependencies, development dependencies are local-only and will _not_ be included in the project requirements when published to PyPI or other indexes. As such, development dependencies are included under `[tool.uv]` instead of `[project]`. 
 
 Development dependencies can have entries in `tool.uv.sources` the same as normal dependencies.
 
-```toml
+```toml title="pyproject.toml"
 [tool.uv]
 dev-dependencies = [
   "pytest >=8.1.1,<9"
 ]
 ```
 
+To add a development dependency, include the `--dev` flag:
+
+```console
+$ uv add ruff --dev`
+```
+
 ## PEP 508
 
 [PEP 508](https://peps.python.org/pep-0508/) defines a syntax for dependency specification. It is composed of, in order:
@@ -182,4 +263,16 @@ There are some limitations to editables (mainly: the build backend needs to supp
 native modules aren't recompiled before import), but they are useful for development, as the
 virtual environment will always use the latest changes to the package.
 
-uv uses editable installation for workspace packages and patched dependencies by default.
+uv uses editable installation for workspace packages by default.
+
+To add an editable dependency, use the `--editable` flag:
+
+```console
+$ uv add --editable ./path/foo
+```
+
+Or, to opt-out of using an editable dependency in a workspace:
+
+```console
+$ uv add --no-editable ./path/foo
+```

docs/features.md

@@ -1,5 +1,5 @@
 
-# Feature overview
+# Features
 
 uv supports the full Python development experience — from installing Python and hacking on simple scripts to working on large projects that support multiple Python versions and platforms.
 
@@ -100,24 +100,4 @@ Managing and inspecting uv's state, such as the cache, storage directories, or p
 
 ## Next steps
 
-Check out one of our guides to get started: 
+Check out the [documentation overview](./overview.md) for a list of guides and concepts.
-
-- [Installing Python](./guides/install-python.md) 
-- [Running scripts](./guides/scripts.md) 
-- [Using tools](./guides/tools.md) 
-- [Working on projects](./guides/projects.md) 
-- [Using in Docker](./guides/integration/docker.md)
-- [Using with pre-commit](./guides/integration/pre-commit.md)
-- [Using in GitHub Actions](./guides/integration/github.md)
-- [Using with commercial package indexes](./guides/integration/commercial-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)

docs/guides/integration/commercial-indexes.md

@@ -33,3 +33,7 @@ export UV_KEYRING_PROVIDER=subprocess
 # Configure the index URL with the username
 export UV_EXTRA_INDEX_URL=https://VssSessionToken@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/
 ```
+
+## Other indexes
+
+uv is also known to work with JFrog's Artifactory, the Google Cloud Artifact Registry, and AWS Code Artifact.

docs/guides/integration/docker.md

@@ -12,14 +12,14 @@ docker run ghcr.io/astral-sh/uv --help
 
 uv can be installed by copying from the official Docker image:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 FROM python:3.12-slim-bullseye
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
 ```
 
 Or with the standalone installer:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 FROM python:3.12-slim-bullseye
 RUN apt-get update && apt-get install -y curl --no-install-recommends
 RUN curl -LsSf https://astral.sh/uv/install.sh | sh
@@ -36,19 +36,19 @@ Once uv is installed in an image, it can be used to install some packages.
 
 The system Python environment is safe to use this context, since a container is already isolated. The `--system` flag can be used to install in the system environment:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 RUN uv pip install --system ruff
 ```
 
 To use the system Python environment by default, set the `UV_SYSTEM_PYTHON` variable:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 ENV UV_SYSTEM_PYTHON=1
 ```
 
 Alternatively, a virtual environment can be created and activated:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 RUN uv venv /opt/venv
 # Use the virtual environment automatically
 ENV VIRTUAL_ENV=/opt/venv
@@ -58,7 +58,7 @@ ENV PATH="/opt/venv/bin:$PATH"
 
 When using a virtual environment, the `--system` flag should be omitted from uv invocations:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 RUN uv pip install ruff
 ```
 
@@ -66,7 +66,7 @@ RUN uv pip install ruff
 
 To install requirements files, copy them into the container:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 COPY requirements.txt .
 RUN uv pip install -r requirements.txt
 ```
@@ -75,7 +75,7 @@ RUN uv pip install -r requirements.txt
 
 When installing a project alongside requirements, it is prudent to separate copying the requirements from the rest of the source code. This allows the dependencies of the project (which do not change often) to be cached separately from the project itself (which changes very frequently).
 
-```dockerfile
+```dockerfile title="Dockerfile"
 COPY pyproject.toml .
 RUN uv pip install -r pyproject.toml
 COPY . .
@@ -88,7 +88,7 @@ RUN uv pip install -e .
 
 If uv isn't needed in the final image, the binary can be mounted in each invocation:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 RUN --mount=from=uv,source=/uv,target=/bin/uv \
     uv pip install --system ruff
 ```
@@ -97,7 +97,7 @@ RUN --mount=from=uv,source=/uv,target=/bin/uv \
 
 A [cache mount](https://docs.docker.com/build/guide/mounts/#add-a-cache-mount) can be used to improve performance across builds:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 RUN --mount=type=cache,target=/root/.cache/uv \
  ./uv pip install -r requirements.txt -->
 ```
@@ -105,7 +105,7 @@ RUN --mount=type=cache,target=/root/.cache/uv \
 Note the cache directory's location can be determined with the `uv cache dir` command.
 Alternatively, the cache can be set to a constant location:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 ENV UV_CACHE_DIR=/opt/uv-cache/
 ```
 

docs/guides/integration/github.md

@@ -6,7 +6,7 @@ uv installation differs depending on the platform.
 
 ### on Unix
 
-```yaml
+```yaml title="example.yml"
 name: Example on Unix
 
 jobs:
@@ -24,7 +24,7 @@ jobs:
 
 ### on Windows
 
-```yaml
+```yaml title="example.yml"
 name: Example on Windows
 
 jobs:
@@ -43,7 +43,7 @@ jobs:
 
 ### Using a matrix
 
-```yaml
+```yaml title="example.yml"
 name: Example
 
 jobs:
@@ -78,7 +78,7 @@ jobs:
 
 Python can be installed with the `python install` command:
 
-```yaml
+```yaml title="example.yml"
 steps:
   # ... setup up uv ...
 
@@ -90,7 +90,7 @@ This will respect the Python version pinned in the project.
 
 Or, when using a matrix, as in:
 
-```yaml
+```yaml title="example.yml"
 strategy:
   matrix:
     python-version:
@@ -101,7 +101,7 @@ strategy:
 
 Provide the version to the `python install` invocation:
 
-```yaml
+```yaml title="example.yml"
 steps:
   # ... setup up uv ...
 
@@ -111,7 +111,7 @@ steps:
 
 Alternatively, the official GitHub `setup-python` action can be used. This is generally faster, but will not respect the project's pinned Python version.
 
-```yaml
+```yaml title="example.yml"
 steps:
   - name: "Set up Python"
     uses: actions/setup-python@v5
@@ -123,7 +123,7 @@ steps:
 
 Once uv and Python are installed, the project can be installed with `uv sync` and commands can be run in the environment with `uv run`:
 
-```yaml
+```yaml title="example.yml"
 steps:
   # ... setup up Python and uv ...
 
@@ -139,7 +139,7 @@ steps:
 
 If using the `uv pip` interface instead of the uv project interface, uv requires a virtual environment by default. To allow installing packages into the system environment, use the `--system` flag on all `uv` invocations or set the `UV_SYSTEM_PYTHON` variable, e.g.:
 
-```yaml
+```yaml title="example.yml"
 steps:
   - name: Allow uv to use the system Python by default
     run: echo "UV_SYSTEM_PYTHON=1" >> $GITHUB_ENV
@@ -147,7 +147,7 @@ steps:
 
 Now, `uv pip` can modify the system environment without creating and activating a virtual environment.
 
-```yaml
+```yaml title="example.yml"
 steps:
   # ... setup up Python and uv ...
 

docs/guides/integration/pre-commit.md

@@ -4,7 +4,7 @@ An official pre-commit hook is provided at [`astral-sh/uv-pre-commit`](https://g
 
 To compile requirements via pre-commit, add the following to the `.pre-commit-config.yaml`:
 
-```yaml
+```yaml title=".pre-commit-config.yaml"
 - repo: https://github.com/astral-sh/uv-pre-commit
   # uv version.
   rev: 0.2.27
@@ -16,7 +16,7 @@ To compile requirements via pre-commit, add the following to the `.pre-commit-co
 
 To compile alternative files, modify `args` and `files`:
 
-```yaml
+```yaml title=".pre-commit-config.yaml"
 - repo: https://github.com/astral-sh/uv-pre-commit
   # uv version.
   rev: 0.2.27
@@ -29,7 +29,7 @@ To compile alternative files, modify `args` and `files`:
 
 To run the hook over multiple files at the same time:
 
-```yaml
+```yaml title=".pre-commit-config.yaml"
 - repo: https://github.com/astral-sh/uv-pre-commit
   # uv version.
   rev: 0.2.27

docs/guides/projects.md

@@ -21,7 +21,7 @@ $ uv init
 
 This will create the following directory structure:
 
-```
+```text
 .
 ├── pyproject.toml
 ├── README.md
@@ -52,7 +52,7 @@ run a project command.
 
 The `pyproject.toml` contains metadata about your project:
 
-```toml
+```toml title="pyproject.toml"
 [project]
 name = "hello-world"
 version = "0.1.0"

docs/guides/scripts.md

@@ -7,7 +7,7 @@ script dependencies are properly managed inside and outside of projects.
 
 If your script has no dependencies, you can execute it with `uv run`:
 
-```python
+```python title="example.py"
 print("Hello world")
 ```
 
@@ -33,7 +33,7 @@ $ uv run example.py
 
 Arguments may be provided to the script:
 
-```python
+```python title="example.py"
 import sys
 
 print(" ".join(sys.argv[1:]))
@@ -63,7 +63,7 @@ of dependencies that are required for the script. Generally, it's recommended to
 
 For example, the following script requires `rich`.
 
-```python
+```python title="example.py"
 import time
 from rich.progress import track
 
@@ -104,7 +104,7 @@ Python recently added a standard format for [inline script metadata](https://pac
 
 To use inline script metadata, include a `script` section at the top of the script:
 
-```python
+```python title="example.py"
 # /// script
 # dependencies = [
 #   "requests<3",
@@ -140,7 +140,7 @@ $ uv run example.py
 
 uv also supports Python version requirements:
 
-```python
+```python title="example.py"
 # /// script
 # requires-python = ">=3.12"
 # dependencies = []
@@ -159,7 +159,7 @@ Note that when using inline script metadata, even if `uv run` is used in a _proj
 
 uv allows arbitrary Python versions to be requested on each script invocation, for example:
 
-```python
+```python title="example.py"
 import sys
 
 print(".".join(map(str, sys.version_info[:3])))

docs/index.md

@@ -6,7 +6,7 @@
   <a href="https://discord.gg/astral-sh"><img src="https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white" /></a>
 </div>
 
-An extremely fast Python version, package, and project manager, written in Rust.
+An extremely fast Python package and project manager, written in Rust.
 
 <p align="center">
   <img alt="Shows a bar chart with benchmark results." src="https://github.com/astral-sh/uv/assets/1309177/629e59c0-9c6e-4013-9ad4-adb2bcf5080d#only-light">
@@ -24,27 +24,20 @@ An extremely fast Python version, package, and project manager, written in Rust.
 
 - 🐍 [Installs and manages](./guides/install-python.md) Python versions.
 - 🛠️ [Executes and installs](./guides/tools.md) commands provided by Python packages.
-- ❇️ [Runs scripts](./guides/scripts.md) with inline dependency metadata.
+- ❇️ [Runs scripts](./guides/scripts.md) with [inline dependency metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata).
-- 🗂️ Provides comprehensive project management, with a multi-platform lock file.
+- 🗂️ Provides [comprehensive project management](./guides/projects.md), with a multi-platform lock file.
-- 🏢 Supports Cargo-style workspaces for large projects.
+- 🏢 Supports Cargo-style [workspaces](./workspaces.md) for large projects.
-- 🚀 A replacement for `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, and more.
+- 🚀 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`).
 - 🧪 Tested at-scale against the top 10,000 PyPI packages.
-- 💾 Disk-space efficient, with a global cache for dependency deduplication.
+- 💾 Disk-space efficient, with a [global cache](./cache.md) for dependency deduplication.
 - ⁉️ Best-in-class error messages with a conflict-tracking resolver.
 - ⏬ A static binary that can be installed without Rust or Python via `curl` or `pip`.
 - 🖥️ Support for macOS, Linux, and Windows.
 
 uv is backed by [Astral](https://astral.sh), the creators of [Ruff](https://github.com/astral-sh/ruff).
 
-## Replacement for `pip` and `pip-tools`
-
-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.
-
-uv extends these interfaces with advanced features, such as dependency version overrides, multi-platform resolutions, reproducible resolutions, alternative resolution strategies, and more.
-
 ## Getting started
 
 Install uv with our official standalone installer:
@@ -57,4 +50,136 @@ curl -LsSf https://astral.sh/uv/install.sh | sh
 powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
-Then, check out the [first steps](./first-steps.md) or see more [installation methods](./installation.md).
+Then, check out the [first steps](./first-steps.md), see more [installation methods](./installation.md), or read on for a brief overview.
+
+## Project management
+
+uv can manage project dependencies and environments:
+
+```console
+$ uv init example
+Initialized project `example` at `/home/user/example`
+
+$ cd example
+
+$ uv add ruff
+Creating virtualenv at: .venv
+Resolved 2 packages in 170ms
+   Built example @ file:///home/user/example
+Prepared 2 packages in 627ms
+Installed 2 packages in 1ms
+ + example==0.1.0 (from file:///home/user/example)
+ + ruff==0.5.4
+
+$ uv run -- ruff check
+All checks passed!
+```
+
+See the [project guide](./guides/projects.md) to get started.
+
+## Tool management
+
+uv provides an interface for executing and installing command-line tools provided by Python packages, similar to `pipx`. 
+
+Run a tool in an ephemeral environment with `uvx`:
+
+```console
+$ uvx pycowsay 'hello world!'
+Resolved 1 package in 167ms
+Installed 1 package in 9ms
+ + pycowsay==0.0.0.2
+  """
+
+  ------------
+< hello world! >
+  ------------
+   \   ^__^
+    \  (oo)\_______
+       (__)\       )\/\
+           ||----w |
+           ||     ||
+```
+
+Install a tool with `uv tool install`:
+
+```console
+$ uv tool install ruff
+Resolved 1 package in 6ms
+Installed 1 package in 2ms
+ + ruff==0.5.4
+Installed 1 executable: ruff
+
+$ ruff --version
+ruff 0.5.4
+```
+
+See the [tools guide](./guides/tools.md) to get started.
+
+## Python management
+
+uv supports installing Python and managing multiple Python versions.
+
+Install the Python versions your project requires:
+
+```console
+$ uv python install 3.10 3.11 3.12
+warning: `uv python install` is experimental and may change without warning
+Searching for Python versions matching: Python 3.10
+Searching for Python versions matching: Python 3.11
+Searching for Python versions matching: Python 3.12
+Installed 3 versions in 3.42s
+ + cpython-3.10.14-macos-aarch64-none
+ + cpython-3.11.9-macos-aarch64-none
+ + cpython-3.12.4-macos-aarch64-none
+```
+
+Or, fetch Python versions on demand:
+
+```console
+$ uv venv --python 3.12.0
+Creating virtualenv at: .venv
+Activate with: source .venv/bin/activate
+```
+
+See the [installing Python guide](./guides/install-python.md) to get started.
+
+## Package management
+
+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.
+
+uv extends these interfaces with advanced features, such as dependency version overrides, multi-platform resolutions, reproducible resolutions, alternative resolution strategies, and more.
+
+Compile requirements into a multi-platform requirements file:
+
+```console
+$ uv pip compile docs/requirements.in --universal --output-file docs/requirements.txt
+Resolved 43 packages in 12ms
+```
+
+Create a virtual environment:
+
+```console
+$ uv venv
+Using Python 3.12.3 interpreter at: /opt/homebrew/opt/python@3.12/bin/python3.12
+Creating virtualenv at: .venv
+Activate with: source .venv/bin/activate
+```
+
+Install the locked requirements:
+
+```console
+$ uv pip sync docs/requirements.txt
+Resolved 43 packages in 11ms
+Installed 43 packages in 208ms
+ + babel==2.15.0
+ + black==24.4.2
+ + certifi==2024.7.4
+ ...
+```
+
+See the [uv pip documentation](./pip/environments.md) to get started.
+
+## Next steps
+
+See the [documentation overview](./overview.md) to learn more about uv.

docs/overview.md

@@ -0,0 +1,23 @@
+# Overview
+
+Check out one of our guides to get started: 
+
+- [Installing Python](./guides/install-python.md) 
+- [Running scripts](./guides/scripts.md) 
+- [Using tools](./guides/tools.md) 
+- [Working on projects](./guides/projects.md) 
+- [Using in Docker](./guides/integration/docker.md)
+- [Using with pre-commit](./guides/integration/pre-commit.md)
+- [Using in GitHub Actions](./guides/integration/github.md)
+- [Using with commercial package indexes](./guides/integration/commercial-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)

docs/pip/compile.md

@@ -97,12 +97,11 @@ including a package in a constraints file will _not_ trigger the installation of
 
 To define an constraint, define a bound for a package:
 
-```text
+```text title="constraints.txt
-# constraints.txt
 pydantic<2.0
 ```
 
-To use a constraint file:
+To use a constraints file:
 
 ```shell
 uv pip compile requirements.in --constraint constraints.txt
@@ -122,15 +121,14 @@ Overrides are most often used to remove upper bounds from a transtive dependency
 
 To define an override, define the new requirement for the problematic package:
 
-```text
+```text overrides.txt
-# override.txt
 c>=2.0
 ```
 
-To use an override file:
+To use an overrides file:
 
 ```shell
-uv pip compile requirements.in --override override.txt
+uv pip compile requirements.in --override overrides.txt
 ```
 
 Now, resolution can succeed. However, note that if `a` is _correct_ that it does not support `c>=2.0` then a runtime error will likely be encountered when using the packages.

docs/pip/dependencies.md

@@ -8,7 +8,7 @@ The `pyproject.toml` file is the Python standard for defining configuration for
 
 To define project dependencies in a `pyproject.toml` file:
 
-```toml
+```toml title="pyproject.toml"
 [project]
 dependencies = [
   "httpx",
@@ -18,7 +18,7 @@ dependencies = [
 
 To define optional dependencies in a `pyproject.toml` file:
 
-```toml
+```toml title="pyproject.toml"
 [project.optional-dependencies]
 cli = [
   "rich",
@@ -36,7 +36,7 @@ It is also common to use a lightweight `requirements.txt` format to declare the
 
 To define dependencies in a `requirements.in` file:
 
-```text
+```text title="requirements.in"
 httpx
 ruff>=0.3.0
 ```

docs/pip/environments.md

@@ -26,8 +26,8 @@ uv venv --python 3.11
 ```
 
 Note this requires the requested Python version to be available on the system.
-However, in preview mode, [uv will download Python for you](../python-versions.md).
+However, if available, uv will download Python for you.
-See the [Python request](../python.md) documentation for more details on requesting Python versions.
+See the [Python version](../python-versions.md) documentation for more details.
 
 ## Using a virtual environment
 

docs/pip/packages.md

@@ -10,7 +10,7 @@ uv pip install flask
 
 To install a package with optional dependencies enabled, e.g., Flask with the "dotenv" extra:
 
-```
+```bash
 uv pip install "flask[dotenv]"
 ```
 

docs/projects.md

@@ -1,55 +1,173 @@
 # Projects
 
+Python projects are help manage Python applications spanning multiple files.
+
+!!! note
+
+    Looking for an introduction to creating a project with uv? See the [projects guide](./guides/projects.md) first.
+
 ## Project metadata
 
-`pyproject.toml`
+Python project metadata is defined in a `pyproject.toml` file. 
 
+`uv init` can be used to create a new project, with a basic `pyproject.toml` and package definition.
+
+A minimal project definition includes a name, version, and description:
+
+```toml title="pyproject.toml"
+[project]
+name = "example"
+version = "0.1.0"
+description = "Add your description here"
 ```
-uv init
+
+Additionally, it's recommended to include a Python version requirement:
+
+```toml title="pyproject.toml"
+[project]
+requires-python = ">=3.12"
 ```
 
+This Python version requirement determines what syntax is valid in the project and affects the versions of dependencies which can be used (they must support the same Python range).
+
+The `pyproject.toml` also lists dependencies of the project. uv supports modifying the standard dependency list from the command line with `uv add` and `uv remove`. uv also supports [extended package sources](./dependencies.md) for advanced users.
+
+See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details on getting started with a `pyproject.toml`.
+
 ## Project environments
 
-`.venv`
+uv creates a virtual environment in a `.venv` directory next to the `pyproject.toml`. This virtual environment contains the project and its dependencies. It is stored inside the project to make it easy for editors to find — they need the environment to give code completions and type hints. It is not recommended to include the `.venv` directory in version control, it should be excluded via a `.gitignore` entry (or similar).
 
-```
+To run a command in the project environment, use `uv run`. Alternatively the project environment can be activated as normal for a virtual environment.
-uv sync
+
+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).
+
+## Lock file
+
+uv creates a `uv.lock` file next to the `pyproject.toml`.
+
+`uv.lock` is a "universal" lockfile that contains exact information about your
+project's dependencies. Unlike the `pyproject.toml` which is used to specify the
+broad requirements of your project, the lockfile contains the exact resolved versions
+that are installed in the project environment. This file should be checked into version
+control, allowing for consistent and reproducible installations across machines.
+
+A "universal" lock file captures packages that would be installed across all possible Python markers such as operating system, architecture, and Python version.
+
+A lock file ensures that developers working on the project are using a consistent set of package versions. Additionally, it ensures when deploying the project as an application that the exact set of used package versions is known. 
+
+The lock file is created and updated during uv invocations that use the project environment, i.e., `uv sync` and `uv run`. The lock file may also be explicitly updated using `uv lock`.
+
+`uv.lock` is a human-readable TOML file but is managed by uv and should not be
+edited manually. There is no Python standard for lock files at this time, so the format of this file is specific to uv and not generally not usable by other tools. 
+
+To avoid updating the lock file during `uv sync` and `uv run` invocations, use the `--frozen` flag.
+
+To assert the lock file is up to date, use the `--locked` flag. If the lock file is not up to date, an error will be raised instead of updating the lock file.
+
+## Managing dependencies
+
+uv is capable of adding, updating, and removing dependencies using the CLI.
+
+To add a dependency:
+
+```console
+$ uv add httpx
 ```
 
-## Lock files
+uv supports adding [editable dependencies](./dependencies.md#editable-dependencies), [development dependencies](./dependencies.md#development-dependencies), [optional dependencies](./dependencies.md#optional-dependencies), and alternative [dependency sources](./dependencies.md#dependency-sources). See the [dependency specification](./dependencies.md) documentation for more details.
 
-```
+uv will raise an error if the dependency cannot be resolved, e.g.:
-uv lock
+
+```console
+$ uv add 'httpx>9999'
+error: Because only httpx<=9999 is available and example==0.1.0 depends on httpx>9999, we can conclude that example==0.1.0 cannot be used.
+And because only example==0.1.0 is available and you require example, we can conclude that the requirements are unsatisfiable.
 ```
 
-## Adding dependencies
+To remove a dependency:
 
-```
+```console
-uv add
+$ uv remove httpx
 ```
 
-### Updating existing dependencies
+To update an existing dependency, e.g., to add a lower bound to the `httpx` version:
-
-<!-- What happens when the same dependency is added multiple times? -->
-
-## Removing dependencies
 
+```console
+$ uv add 'httpx>0.1.0'
 ```
-uv remove
+
+Or, to change the bounds for `httpx`:
+
+```console
+$ uv add 'httpx<0.2.0'
+```
+
+To add a dependency source, e.g., to use `httpx` from GitHub during development:
+
+```console
+$ uv add git+https://github.com/encode/httpx
 ```
 
 ## Running commands
 
+When working on a project, it is installed into virtual environment at `.venv`. This environment is isolated from the current shell by default, so invocations that require the project, e.g., `python -c "import example"`, will fail. Instead, use `uv run` to run commands in the project environment:
+
+```console
+$ uv run python -c "import example"
 ```
-uv run
+
+When using `run`, uv will ensure that the project environment is up to date before running the given command.
+
+The given command can be provided by the project environment or exist outside of it, e.g.:
+
+```console
+# Presuming the project provides `example-cli`
+$ uv run example-cli foo
+
+# Running a `bash` script that requires the project to be available
+$ uv run bash scripts/foo.sh
 ```
 
 ### Running commands with additional dependencies
 
+Additional dependencies or different versions of dependencies can be requested per invocation.
+
+The `--with` option is used to include a dependency for the invocation, e.g., to request a different version of `httpx`:
+
+```console
+$ uv run --with httpx==0.26.0 python -c "import httpx; print(httpx.__version__)"
+0.26.0
+$ uv run --with httpx==0.25.0 python -c "import httpx; print(httpx.__version__)"
+0.25.0
+```
+
+The requested version will be respected regardless of the project's requirements. For example, even if the project requires `httpx==0.24.0`, the output above would be the same. 
+
 ### 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.
 
+For example, given a script:
+
+```python  title="example.py"
+# /// script
+# dependencies = [
+#   "httpx",
+# ]
+# ///
+
+import httpx
+
+resp = httpx.get("https://peps.python.org/api/peps.json")
+data = resp.json()
+print([(k, v["title"]) for k, v in data.items()][:10])
+```
+
+The invocation `uv run example.py` would run _isolated_ from the project with only the given dependencies listed.
+
 ## Projects with many packages
 
-See the [workspaces](./workspaces.md) documentation.
+If working in a project composed of many packages, see the [workspaces](./workspaces.md) documentation.

docs/resolution.md

@@ -16,13 +16,13 @@ without restricting the versions of transitive dependencies.
 
 For example, given the following `requirements.in` file:
 
-```text
+```text title="requirements.in"
 flask>=2.0.0
 ```
 
 Running `uv pip compile requirements.in` would produce the following `requirements.txt` file:
 
-```text
+```text title="requirements.txt"
 # This file was autogenerated by uv via the following command:
 #    uv pip compile requirements.in
 blinker==1.7.0
@@ -44,7 +44,7 @@ werkzeug==3.0.1
 
 However, `uv pip compile --resolution=lowest requirements.in` would instead produce:
 
-```text
+```text title="requirements.in"
 # This file was autogenerated by uv via the following command:
 #    uv pip compile requirements.in --resolution=lowest
 click==7.1.2

docs/tools.md

@@ -30,25 +30,25 @@ Tool environments may be either mutated or re-created by subsequent `uv tool ins
 
 To upgrade a single package in a tool environment:
 
-```
+```console
 $ uv tool install black --upgrade-package click
 ```
 
 To upgrade all packages in a tool environment
 
-```
+```console
 $ uv tool install black --upgrade
 ```
 
 To reinstall a single package in a tool environment:
 
-```
+```console
 $ uv tool install black --reinstall-package click
 ```
 
 To reinstall all packages in a tool environment
 
-```
+```console
 $ uv tool install black --reinstall
 ```
 

docs/workspaces.md

@@ -29,7 +29,7 @@ There a two main workspace structures: A **root package with helpers** and a **f
 
 The root workspace layout defines one main package in the root of the repository, with helper packages in `packages`. In this example `albatross/pyproject.toml` has both a `project` section and a `tool.uv.workspace` section.
 
-```
+```text
 albatross
 ├── packages
 │   ├── provider_a
@@ -56,7 +56,7 @@ In the flat layout, all packages are in the `packages` directory, and the root
 `pyproject.toml` defines a so-called virtual workspace. In this example `albatross/pyproject.toml` has only a `tool.uv.workspace` section,
 but no `project`.
 
-```
+```text
 albatross
 ├── packages
 │   ├── albatross

mkdocs.template.yml

@@ -72,7 +72,8 @@ nav:
   - Getting started:
       - Installation: installation.md
       - First steps: first-steps.md
-      - Feature overview: features.md
+      - Features: features.md
+      - Overview: overview.md
   - Guides:
       - Installing Python: guides/install-python.md
       - Running scripts: guides/scripts.md