Add required environment marker example to hint by Prhmma · Pull Request #16244 · astral-sh/uv

Prhmma · 2025-10-10T23:14:24Z

Summary

fixes issue #15938

show platform wheel hint with a concrete tool.uv.required-environments example so users know how to configure compatibility
add WheelTagHint::suggest_environment_marker to pick a sensible environment marker based on the available wheel tags
update the sync_required_environment_hint integration snapshot to expect the new multi-line hint

Test Plan

cargo test --package uv --test it -- sync::sync_required_environment_hint

konstin · 2025-10-15T12:57:42Z

crates/uv-resolver/src/lock/mod.rs

        })
    }
+
+    fn suggest_environment_marker(tags: &BTreeSet<PlatformTag>) -> &'static str {


Why are we going through the tags here, instead of using the actual interpreter environment?

Thanks for the comment,
You are right, my initial understanding was the function is called when there are NO compatible wheels available for the current environment. In this case, we want to suggest what environment markers the user could configure to make the available wheels compatible.

but the function should use the actual interpreter environment (best) instead of the available wheel tags (tags). I will push the fix shortly

@konstin
I made some changes and pushed a new commit, but it got more complicated than I expected, because I had to pipe the value across for the environment, which means more changes for a UX issue.
Please let me know your thoughts.

Thanks

Use actual interpreter environment instead of inferring markers from platform tags when generating environment marker examples in error hints. Threads MarkerEnvironment through the call chain from interpreter to suggest_environment_marker function.

konstin · 2025-10-16T20:00:21Z

crates/uv-resolver/src/lock/mod.rs

        dependency_metadata: &DependencyMetadata,
        indexes: Option<&IndexLocations>,
        tags: &Tags,
+        markers: &uv_pep508::MarkerEnvironment,


nit: We generally do use uv_pep508::MarkerEnvironment and then use &MarkerEnvironment

konstin · 2025-10-16T20:04:07Z

crates/uv-resolver/src/lock/mod.rs

+        let platform_machine = markers.platform_machine();
+
+        // Generate the marker string based on actual environment values
+        if platform_machine.is_empty() {


When would this markers be empty?

This is Python output

>>> import platform >>> help(platform.machine) Help on function machine in module platform: machine() Returns the machine type, e.g. 'i386' An empty string is returned if the value cannot be determined.

This is the defensive line, just to make sure we are safe.

Interesting, I don't think I've ever seen this value be empty, but it makes sense to keep it since it's documented.

konstin · 2025-10-16T20:27:37Z

crates/uv-resolver/src/lock/mod.rs

+                    writeln!(
+                        f,
+                        "{}",
+                        "For example, add this to your pyproject.toml:".dimmed()
+                    )?;
+                    writeln!(f, "    {}", "[tool.uv]".dimmed())?;
+                    writeln!(f, "    {} = [", "required-environments".green())?;
+                    writeln!(
+                        f,
+                        "        \"{}\",  {}",
+                        example_marker.cyan().dimmed(),
+                        "# Adjust the platform/architecture as needed".dimmed()
+                    )?;
+                    writeln!(f, "    {}", "]".dimmed())


Showing multiline code blocks in the terminal is hard, and we currently don't have a good general diagnostic system (like showing diffs for sections we want to change). For example, with the current layout, you'd get extra indentation when copying, while triple backticks look out-of-place in terminal output, etc. What about rolling this into a single line to avoid the formatting question?

consider adding "sys_platform == '[PLATFORM]' and platform_machine == '[MACHINE]'" to tool.uv.required-environments to ensure uv resolves to a version with compatible wheels`

pushed the changes, thanks

konstin

Thank you!

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).

fix: add required environment marker example to hint

80fb8fb

konstin reviewed Oct 15, 2025

View reviewed changes

Prhmma force-pushed the fix-required-env-hint-example branch from c74be7b to eff4c1a Compare October 15, 2025 20:46

Prhmma force-pushed the fix-required-env-hint-example branch from eff4c1a to b021dbe Compare October 15, 2025 20:55

konstin reviewed Oct 16, 2025

View reviewed changes

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

konstin changed the title ~~fix: add required environment marker example to hint~~ Add required environment marker example to hint Oct 16, 2025

style: Use imported MarkerEnvironment instead of full path

f1639d2

Prhmma force-pushed the fix-required-env-hint-example branch 2 times, most recently from c8057e5 to 93b5a60 Compare October 17, 2025 13:05

Replace multiline hint example with inline marker suggestion

a7cda8f

Prhmma force-pushed the fix-required-env-hint-example branch from 93b5a60 to a7cda8f Compare October 17, 2025 13:36

konstin approved these changes Oct 20, 2025

View reviewed changes

konstin merged commit ed3f99a into astral-sh:main Oct 20, 2025
100 checks passed

BrewTestBot mentioned this pull request Oct 21, 2025

uv 0.9.5 Homebrew/homebrew-core#250541

Merged

konstin mentioned this pull request Dec 18, 2025

Add a concrete example to required-environments hint #15938

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Add required environment marker example to hint#16244

Add required environment marker example to hint#16244
konstin merged 4 commits intoastral-sh:mainfrom
Prhmma:fix-required-env-hint-example

Prhmma commented Oct 10, 2025 •

edited

Loading

Uh oh!

konstin Oct 15, 2025

Uh oh!

Prhmma Oct 15, 2025

Uh oh!

Prhmma Oct 15, 2025

Uh oh!

konstin Oct 16, 2025

Uh oh!

konstin Oct 16, 2025

Uh oh!

Prhmma Oct 17, 2025 •

edited

Loading

Uh oh!

konstin Oct 20, 2025

Uh oh!

konstin Oct 16, 2025

Uh oh!

Prhmma Oct 17, 2025

Uh oh!

konstin left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

Prhmma commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test Plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Prhmma Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Prhmma commented Oct 10, 2025 •

edited

Loading

Prhmma Oct 17, 2025 •

edited

Loading