From 782a862e92b8a1484ecd1a0db625383ff2e489c3 Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Sat, 2 Mar 2024 07:07:57 -0800 Subject: [PATCH] Add caveats on `--system` support to the README (#2131) ## Summary Covering some of the limitations from https://github.com/astral-sh/uv/issues/2113. --- README.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 43fa4ef7f..e4ddfc52d 100644 --- a/README.md +++ b/README.md @@ -169,12 +169,14 @@ search for a Python interpreter matching that version in the following order: - On Windows, the Python interpreter returned by `py --list-paths` that matches the requested version. +### Installing into arbitrary Python environments + Since uv has no dependency on Python, it can even 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. -Finally, uv can also install into 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 +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. For convenience, `uv pip install --system` will install into the system Python environment, as an @@ -182,6 +184,13 @@ approximate shorthand for, e.g., `uv pip install --python=$(which python3)`. Tho recommend the use of virtual environments for dependency management, `--system` is intended to enable the use of `uv` in continuous integration and containerized 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 +Python on Debian prior to Python 3.10 is unsupported due to the [distribution's patching +of `distutils` (but not `sysconfig`)](https://ffy00.github.io/blog/02-python-debian-and-the-install-locations/). +While we always recommend the use of virtual environments, `uv` considers them to be required in +these non-standard environments. + ### Git authentication uv allows packages to be installed from Git and supports the following schemes for authenticating with private