From 88ba1e90a087e3acf51f097ae5435127ce5e6bb8 Mon Sep 17 00:00:00 2001
From: Zanie Blue <contact@zanie.dev>
Date: Tue, 3 Sep 2024 18:47:05 -0500
Subject: [PATCH] Add docs for `UV_PROJECT_ENVIRONMENT` (#6987)

---
 docs/concepts/projects.md         | 24 ++++++++++++++++++++++++
 docs/configuration/environment.md |  4 ++++
 docs/guides/integration/docker.md |  7 +++++++
 docs/guides/integration/github.md |  6 ++++++
 4 files changed, 41 insertions(+)

diff --git a/docs/concepts/projects.md b/docs/concepts/projects.md
index 757cdc07894a..cbe9648c712b 100644
--- a/docs/concepts/projects.md
+++ b/docs/concepts/projects.md
@@ -277,6 +277,30 @@ use [`uvx`](../guides/tools.md) or
     managed = false
     ```
 
+### Custom project environment paths
+
+The `UV_PROJECT_ENVIRONMENT` environment variable can be used to configure the project virtual
+environment path (`.venv` by default).
+
+If a relative path is provided, it will be resolved relative to the workspace root. If an absolute
+path is provided, it will be used as-is, i.e. a child directory will not be created for the
+environment. If an environment is not present at the provided path, uv will create it.
+
+This option can be used to write to the system Python environment, though it is not recommended.
+`uv sync` will remove extraneous packages from the environment by default and, as such, may leave
+the system in a broken state.
+
+!!! important
+
+    If an absolute path is provided and the setting is used across multiple projects, the
+    environment will be overwritten by invocations in each project. This setting is only recommended
+    for use in CI or Docker images.
+
+!!! note
+
+    uv does not read the `VIRTUAL_ENV` environment variable during project operations. A warning
+    will be displayed if `VIRTUAL_ENV` is set to a different path than the project's environment.
+
 ## Project lockfile
 
 uv creates a `uv.lock` file next to the `pyproject.toml`.
diff --git a/docs/configuration/environment.md b/docs/configuration/environment.md
index 1a4e995fdc04..67e028212285 100644
--- a/docs/configuration/environment.md
+++ b/docs/configuration/environment.md
@@ -76,6 +76,10 @@ In addition, uv respects the following environment variables:
   packages.
 - `UV_TOOL_DIR`: Used to specify the directory where uv will store managed tools.
 - `UV_TOOL_BIN_DIR`: Used to specify the "bin" directory where uv will install tool executables.
+- `UV_PROJECT_ENVIRONMENT`: Use to specify the path to the directory to use for a project virtual
+  environment. See the
+  [project documentation](../concepts/projects.md#custom-project-environment-paths) for more
+  details.
 - `UV_PYTHON_INSTALL_DIR`: Used to specify the directory where uv will store managed Python
   installations.
 - `UV_PYTHON_INSTALL_MIRROR`: Managed Python installations are downloaded from
diff --git a/docs/guides/integration/docker.md b/docs/guides/integration/docker.md
index f04a90586279..5de1726c9f12 100644
--- a/docs/guides/integration/docker.md
+++ b/docs/guides/integration/docker.md
@@ -189,6 +189,13 @@ Or, you can use `uv run` for any commands that require the environment:
 RUN uv run some_script.py
 ```
 
+!!! tip
+
+    Alternatively, the
+    [`UV_PROJECT_ENVIRONMENT` setting](../../concepts/projects.md#custom-project-environment-paths) can
+    be set before syncing to install to the system Python environment and skip environment activation
+    entirely.
+
 ### Using installed tools
 
 To use installed tools, ensure the [tool bin directory](../../concepts/tools.md#the-bin-directory)
diff --git a/docs/guides/integration/github.md b/docs/guides/integration/github.md
index 2f8d23089f0c..6bca42399f1e 100644
--- a/docs/guides/integration/github.md
+++ b/docs/guides/integration/github.md
@@ -229,6 +229,12 @@ steps:
     run: uv run pytest tests
 ```
 
+!!! tip
+
+    The
+    [`UV_PROJECT_ENVIRONMENT` setting](../../concepts/projects.md#custom-project-environment-paths) can
+    be used to install to the system Python environment instead of creating a virtual environment.
+
 ## Caching
 
 It may improve CI times to store uv's cache across workflow runs.