Add docs for UV_PROJECT_ENVIRONMENT

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`.

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

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)

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.