`uv pip install --system` fails because python installation is managed by uv?

[MillieFD]

Summary

Summary of the issue

Attempting to install a package for all users with the command uv pip install --system fails because the python installation is "externally managed" by uv itself.

error: The interpreter at /opt/uv/python/cpython-3.13.2-linux-aarch64-gnu is externally managed, and indicates the following:
This Python installation is managed by uv and should not be modified.

What am I trying to achieve?

I'm using a Raspberry Pi 5 to control a robot in our lab. I've written a Python package (called thormotion) which can be used to control the robot. I want to make uv, python 3.13 and the thormotion package available by default to all users on the raspberry pi, without needing to re-install the package for each new user.

What have I done so far?

Starting from a fresh install of Raspberry Pi OS Lite 64-bit, I installed uv into a non-user-specific location.

curl -LsSf https://astral.sh/uv/install.sh | sudo env UV_INSTALL_DIR="/usr/local/bin" sh

This works as expected. Running uv --version returns uv 0.6.6 when logged in as any user.

Next, I installed python 3.13, again setting the environment variables to non-user-specific locations.

sudo UV_PYTHON_INSTALL_DIR=/opt/uv/python UV_PYTHON_BIN_DIR=/usr/local/bin uv python install --default --preview

Calling uv python list is able to show this new python installation when logged in as any user. Note that, even though I set the --default flag, python --version still returns Python 3.11.2 which is the default python executable that come pre-installed on Raspberry Pi OS. That's not necessarily a deal-breaker, but was unexpected from my understanding of the --default flag's purpose.

Exploring the issue

At this stage, I was ready to install the thormotion package for the new python 3.13 installation to make it available to all users.

Running uv pip install thormotion returned the following error:

error: No virtual environment found; run `uv venv` to create an environment, or pass `--system` to install into a non-virtual environment

Okay, fair enough. The hint is pretty clear that I need to add the --system flag to install packages into the system Python environment. Lets try it:

millie@raspberrypi:~ $ uv pip install --system --python 3.13 thormotion
Using Python 3.13.2 environment at: /opt/uv/python/cpython-3.13.2-linux-aarch64-gnu
error: The interpreter at /opt/uv/python/cpython-3.13.2-linux-aarch64-gnu is externally managed, and indicates the following:

  This Python installation is managed by uv and should not be modified.

Consider creating a virtual environment with `uv venv`.

Now this confused me. Of course the Python installation is managed by uv, that's why I'm running a uv command. What is the purpose of the --system flag if it can't operate on uv managed Python installations?

Workaround

After trying various alternatives, I was able to get the thormotion package to install by adding the --break-system-packages flag.

uv pip install --system --python 3.13 --break-system-packages thormotion

Whilst this does work, the fact that --break-system-packages is required makes me feel that I may have completely misunderstood the purpose of the --system flag.

Final questions

1. Is this behaviour a bug, or if not, what is the actual intended purpose for the --system flag?
2. Is my --break-system-packages workaround the recommended solution, or is there a better way?

Platform

Raspberry Pi OS Lite (64-bit, based on Debian Bookworm)

Version

0.6.6

Python version

3.13.2

[zanieb]

It's intentional that the global Python environment is not mutable. The --system flag is for targeting system environments not managed by uv, and largely exists for backwards compatibility — we wouldn't recommend using it generally.

I'd create a virtual environment in a shared location, then activate it by default by placing the Python interpreter at the front of the PATH. Basically as described in https://docs.astral.sh/uv/guides/integration/docker/#using-the-environment

We should probably add a dedicated hint to uv pip install when the interpreter is managed by uv. I think that'd be better than recommending --system.

Note that, even though I set the --default flag, python --version still returns Python 3.11.2 which is the default python executable that come pre-installed on Raspberry Pi OS. That's not necessarily a deal-breaker, but was unexpected from my understanding of the --default flag's purpose.

Is the UV_PYTHON_BIN_DIR at the front of your PATH? Is there an existing python executable there? We won't replace an externally-managed Python executable without the --force flag. Was there a warning on install? The verbose logs (-v) would probably make what's happening clearer.

[keramblock]

Hi @zanieb we want to use uv in github ci, and there is python as a shell approach:

      - name: Output test results
        shell: python
        run: |
          import xml.etree.ElementTree as ET
          import os

          def parse_junit_report(file_path):
              blah-blah-blah

          # Call the function with your junit xml report file path
          parse_junit_report('test-results.xml')

And for one of such actions I need pyJWT lib to make it work.

I already made one python work by default using:
RUN uv python install ${DEFAULT_PYTHON_VERSION} --default --preview

And make our dev tooling work:
RUN for req in $(cat dev-requirements.txt); do uv tool install ${req}; done

Could you please help me to understand how should I prepare runner image with uv to have python available globally and pyjwt in it?

The thing is that i do not want to any venv activated by default as every project is free to choose which venv with which python version they want to use and I do not force them.

P.S. for now I managed to overcome that using:
uv pip -v install --system --break-system-packages -r requirements.txt
But this is really ugly solution IMO

[davidghiurco]

It's intentional that the global Python environment is not mutable. The --system flag is for targeting system environments not managed by uv, and largely exists for backwards compatibility — we wouldn't recommend using it generally.

I'd create a virtual environment in a shared location, then activate it by default by placing the Python interpreter at the front of the PATH. Basically as described in https://docs.astral.sh/uv/guides/integration/docker/#using-the-environment

We should probably add a dedicated hint to uv pip install when the interpreter is managed by uv. I think that'd be better than recommending --system.

So if I install a uv-managed python interpreter in a container ... I need 2 copies of the interpreter — one global, one venv — just to satisfy a blind "must use venv" requirement? That is a waste of space & hardly seems reasonable.

In the container scenario, containerization already achieves purpose-built isolation that is intended by venv — making venv obsolete.

EDIT: uv pip install <my-package> --system --break-system-packages does seem to overcome this limitation, but --break-system-packages is not mentioned as an option in the error messages produced without it in the command invocation.

EDIT 2: uv tool install <my-package> appears to be the cleaner alternative to installing a library in the global python interpreter managed by uv

[zanieb]

That is a waste of space

Can you quantify this claim? Virtual environments are really lightweight.

[jm-positron]

I think the weight of a venv is orthogonal to whether or not it is necessary. I believe the point is that because isolation is already achieved by the containerized environment, creating a virtual environment in additional to the system environment is unnecessary duplication, and thus a waste.