Add docs for UV_PROJECT_ENVIROMENT

astral-sh · Sep 3, 2024 · c28f54d · c28f54d
1 parent 8403a6d
commit c28f54d
Show file tree

Hide file tree

Showing 4 changed files with 40 additions and 0 deletions.
diff --git a/docs/concepts/projects.md b/docs/concepts/projects.md
@@ -277,6 +277,29 @@ use [`uvx`](../guides/tools.md) or
     managed = false
     ```
 
+### Custom project environment paths
+
+The `UV_PROJECT_ENVIRONMENT` environment variable can be used to configure the path to virtual
+environments in projects. If a relative path is provided, it will be resolved relative to the
+workspace root.
+
+If an environment is not present at the given 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, which means if there are
+installed packages relevant to the operation of the system, the system may be broken.
+
+!!! 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
@@ -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
@@ -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
@@ -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.