fix: Add a hint on `uv pip install` failure if the `--system` flag is used to select an externally managed interpreter by cmnemoi · Pull Request #16318 · astral-sh/uv

cmnemoi · 2025-10-15T16:37:35Z

Hello,

Summary

This PR makes the error message clearer when you try to install packages into an externally managed Python environment with the --system flag.
Now, instead of just failing, the error explains that you're hitting this because you explicitly used --system.

This closes #15639.

Test plan

I added a new integration test (install_with_system_interpreter in pip_install.rs) that checks the error message includes the hint.
I tried to run uv pip install --system -r requirements.txt to see the actual error message in action, but had permission issues.

… used to select an externally managed interpreter.

cmnemoi · 2025-10-15T16:38:32Z

crates/uv/tests/it/pip_install.rs

+    // Add a custom filter to replace the system Python path (works on Unix-like systems, Windows and for CPython, PyPy and GraalPy implementations)
+    let filters: Vec<_> = context
+        .filters()
+        .into_iter()
+        .chain(std::iter::once((
+            r"([\\/]).+([\\/])python([\\/])(?:cpython|pypy|graalpy)-\d+\.\d+\.\[X\][^\s]+",
+            "[PYTHON-PATH]",
+        )))
+        .collect();


I am not sure if this is the best way to do this, or if this should be added to context.filters directly.

…system_interpreter test

konstin · 2025-10-20T18:34:37Z

crates/uv/src/commands/pip/install.rs

+                ),
+                None => anyhow::anyhow!(
                    "The interpreter at {} is externally managed. Instead, create a virtual environment with `uv venv`.",
                    environment.root().user_display().cyan()


We should show the hint in both branches

konstin · 2025-10-20T18:35:16Z

crates/uv/src/commands/pip/install.rs

-            } else {
-                Err(anyhow::anyhow!(
+                    if system {
+                        "\nhint: This happens because you used the `--system` flag, which selects the system Python interpreter."


What about the following hint:

The --system flag was used

We usually use indirect language instead of "you used"

konstin · 2025-10-20T18:35:53Z

crates/uv/src/commands/pip/install.rs

-            } else {
-                Err(anyhow::anyhow!(
+                    if system {
+                        "\nhint: This happens because you used the `--system` flag, which selects the system Python interpreter."


We style the hint with:

"hint".bold().cyan(), ":".bold(),

konstin

Thank you!

I had some qualms with #16318 1. The snapshot was specific to uv's managed interpreter due to inclusion of the externally-managed output. This will break downstream distros. We either need to filter the message, or, as done here, install a managed interpreter. 2. It had a custom filter for the interpreter path, which we shouldn't need. If needed, we should fix that in the test context. 3. We already had an implicit hint to create a virtual environment. The change in styling of the new hint hint following it is confusing. It's also confusing to hint creating a virtual environment when `--system` was used. 4. There were unresolved requested changes to the language for the message / it didn't fit stylistic with our existing ones. 5. The message was also very confusing for a uv-managed interpreter, which is both a "system" Python interpreter (in that it's global) and the opposite of a "system" interpreter per UV_PYTHON_PREFERENCE. Also problematic, but not addressed here, is that there are other commands that display an externally-managed message, e.g., `uv pip sync`, but #16318 was just limited to `pip install`. We should not just implement this in one place — I'll open a tracking issue to consolidate and reuse the logic.

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [astral-sh/uv](https://github.com/astral-sh/uv) | patch | `0.9.3` -> `0.9.5` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>astral-sh/uv (astral-sh/uv)</summary> ### [`v0.9.5`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#095) [Compare Source](astral-sh/uv@0.9.4...0.9.5) Released on 2025-10-21. This release contains an upgrade to `astral-tokio-tar`, which addresses a vulnerability in tar extraction on malformed archives with mismatching size information between the ustar header and PAX extensions. While the `astral-tokio-tar` advisory has been graded as "high" due its potential broader impact, the *specific* impact to uv is **low** due to a lack of novel attacker capability. Specifically, uv only processes tar archives from source distributions, which already possess the capability for full arbitrary code execution by design, meaning that an attacker gains no additional capabilities through `astral-tokio-tar`. Regardless, we take the hypothetical risk of parser differentials very seriously. Out of an abundance of caution, we have assigned this upgrade an advisory: <GHSA-w476-p2h3-79g9> ##### Security - Upgrade `astral-tokio-tar` to 0.5.6 to address a parsing differential ([#16387](astral-sh/uv#16387)) ##### Enhancements - Add required environment marker example to hint ([#16244](astral-sh/uv#16244)) - Fix typo in MissingTopLevel warning ([#16351](astral-sh/uv#16351)) - Improve 403 Forbidden error message to indicate package may not exist ([#16353](astral-sh/uv#16353)) - Add a hint on `uv pip install` failure if the `--system` flag is used to select an externally managed interpreter ([#16318](astral-sh/uv#16318)) ##### Bug fixes - Fix backtick escaping for PowerShell ([#16307](astral-sh/uv#16307)) ##### Documentation - Document metadata consistency expectation ([#15683](astral-sh/uv#15683)) - Remove outdated aarch64 musl note ([#16385](astral-sh/uv#16385)) ### [`v0.9.4`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#094) [Compare Source](astral-sh/uv@0.9.3...0.9.4) Released on 2025-10-17. ##### Enhancements - Add CUDA 13.0 support ([#16321](astral-sh/uv#16321)) - Add auto-detection for Intel GPU on Windows ([#16280](astral-sh/uv#16280)) - Implement display of RFC 9457 HTTP error contexts ([#16199](astral-sh/uv#16199)) ##### Bug fixes - Avoid obfuscating pyx tokens in `uv auth token` output ([#16345](astral-sh/uv#16345)) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

cmnemoi added 2 commits October 15, 2025 18:21

fix: Add a hint on uv pip install failure if the --system flag is…

0ef538d

… used to select an externally managed interpreter.

refactor: Remove nested conditionals

7b73b3b

cmnemoi commented Oct 15, 2025

View reviewed changes

cmnemoi added 3 commits October 15, 2025 18:39

style: format code

149d41b

style: apply clippy fixes

3a5aa59

fix: improve regex for Windows Python path filtering in install_with_…

31ed274

…system_interpreter test

cmnemoi mentioned this pull request Oct 15, 2025

On externally managed errors, hint why a system interpreter was selected #15639

Closed

style: apply fmt fixes

3f7d141

cmnemoi force-pushed the fix/15639 branch from adfbc65 to 3f7d141 Compare October 16, 2025 08:25

konstin reviewed Oct 20, 2025

View reviewed changes

cmnemoi added 3 commits October 20, 2025 20:54

refactor: Use passive form for the hint

9c6b5fc

fix: Show the hint on both branches, and style it properly

81b3ef5

refactor: only create anyhow::Error at the very end

ab2b419

konstin approved these changes Oct 21, 2025

View reviewed changes

konstin added the error messages Messaging when something goes wrong label Oct 21, 2025

konstin enabled auto-merge (squash) October 21, 2025 07:37

konstin merged commit 29cec24 into astral-sh:main Oct 21, 2025
182 of 188 checks passed

zanieb mentioned this pull request Oct 21, 2025

Improve hint on pip install --system when externally managed #16392

Merged

BrewTestBot mentioned this pull request Oct 21, 2025

uv 0.9.5 Homebrew/homebrew-core#250541

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

fix: Add a hint on `uv pip install` failure if the `--system` flag is used to select an externally managed interpreter#16318

fix: Add a hint on `uv pip install` failure if the `--system` flag is used to select an externally managed interpreter#16318
konstin merged 9 commits intoastral-sh:mainfrom
cmnemoi-oss:fix/15639

cmnemoi commented Oct 15, 2025

Uh oh!

cmnemoi Oct 15, 2025

Uh oh!

konstin Oct 20, 2025

Uh oh!

konstin Oct 20, 2025

Uh oh!

konstin Oct 20, 2025

Uh oh!

konstin left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

cmnemoi commented Oct 15, 2025

Summary

Test plan

Uh oh!

cmnemoi Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

konstin Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

konstin Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

konstin Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

konstin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants