astral-sh/uv

Add a hint when free-threaded selector is used in `requires-python`

Open

#16963 opened on Dec 3, 2025

View on GitHub
 (5 comments) (1 reaction) (0 assignees)Rust (84,934 stars) (3,111 forks)batch import
enhancementerror messageshelp wanted

Description

Summary

See https://github.com/astral-sh/uv/issues/16951

We should be able to suggest a resolution here

Example

error: Failed to parse: `pyproject.toml`
  Caused by: TOML parse error at line 4, column 19
  |
4 | requires-python = ">=3.14t"
  |                   ^^^^^^^^^
Failed to parse version: after parsing `3.14`, found `t`, which is not part of a valid version:
>=3.14t
^^^^^^^

hint: `requires-python` cannot include a free-threaded selector, consider using `uv python pin 3.14t` instead

Contributor guide

Tech stack
rustpython
Domain
clideveloper experience
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Rust basicsUV error handling patterns
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
85
Research direction
Investigate the version parsing module (likely in crates/uv version or similar) to locate where the error for invalid requires python is raised. Modify the error handling to detect when a 't' suffix is used (free threaded) and emit a hint suggesting 'uv python pin 3.14t'. Refer to the linked issue #16951 and the example error message in the issue body for the expected output format.