From 9a9ebe32627ac0ed8cbd859dffc19144dacc217f Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Mon, 10 Jun 2024 12:19:41 -0400 Subject: [PATCH] Clarify role of `--system` flag in README (#4031) For uv>=0.2.0 behavior Closes #3951 --------- Co-authored-by: David Poznik --- README.md | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 62349290b..9c5fab91b 100644 --- a/README.md +++ b/README.md @@ -180,18 +180,29 @@ search for a Python interpreter matching that version in the following order: ### Installing into arbitrary Python environments -Since uv has no dependency on Python, it can even install into virtual environments other than +Since uv has no dependency on Python, it can install into virtual environments other than its own. For example, setting `VIRTUAL_ENV=/path/to/venv` will cause uv to install into -`/path/to/venv`, no matter where uv is installed. +`/path/to/venv`, regardless of where uv is installed. Note that if `VIRTUAL_ENV` is set to +a directory that is **not** a [PEP 405 compliant](https://peps.python.org/pep-0405/#specification) +virtual environment, it will be ignored. -uv can also install into arbitrary, even non-virtual environments by providing a `--python` argument -to `uv pip sync` or `uv pip install`. For example, `uv pip install --python=/path/to/python` will -install into the environment linked to the `/path/to/python` interpreter. +uv can also install into arbitrary, even non-virtual environments, with the `--python` argument +provided to `uv pip sync` or `uv pip install`. For example, `uv pip install --python=/path/to/python` +will install into the environment linked to the `/path/to/python` interpreter. -For convenience, `uv pip install --system` will install into the system Python environment, as an -approximate shorthand for, e.g., `uv pip install --python=$(which python3)`. Though we generally -recommend the use of virtual environments for dependency management, `--system` is intended to -enable the use of uv in continuous integration and containerized environments. +For convenience, `uv pip install --system` will install into the system Python environment. +Using `--system` is roughly equivalent to `uv pip install --python=$(which python)`, +but note that executables that are linked to virtual environments will be skipped. +Although we generally recommend using virtual environments for dependency management, +`--system` is appropriate in continuous integration and containerized environments. + +The `--system` flag is also used to opt in to mutating system environments. For example, the +the `--python` argument can be used to request a Python version (e.g., `--python 3.12`), and uv will +search for an interpreter that meets the request. If uv finds a system interpreter (e.g., `/usr/lib/python3.12`), +then the `--system` flag is required to allow modification of this non-virtual Python environment. +Without the `--system` flag, uv will ignore any interpreters that are not in virtual environments. +Conversely, when the `--system` flag is provided, uv will ignore any interpreters that *are* +in virtual environments. Installing into system Python across platforms and distributions is notoriously difficult. uv supports the common cases, but will not work in all cases. For example, installing into system @@ -200,6 +211,11 @@ of `distutils` (but not `sysconfig`)](https://ffy00.github.io/blog/02-python-deb While we always recommend the use of virtual environments, uv considers them to be required in these non-standard environments. +If uv is installed in a Python environment, e.g., with `pip`, it can still be used to modify +other environments. However, when invoked with `python -m uv`, uv will default to using the parent +interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for +general usage. + ### Persistent configuration uv supports persistent configuration at both the project- and user-level.