Motivation

We are using setup-uv in CI workflows that build Python packages with native extensions.

Currently, setup-uv generates cache keys based on process.platform (e.g., unknown-linux-gnu). This is too broad for environments where system libraries (like glibc) vary significantly between runner versions (e.g., Ubuntu 20.04 vs 22.04).

The Problem:
If a workflow runs on different OS versions (or if GitHub updates the runner image), setup-uv restores the cache because the key (...-unknown-linux-gnu) hasn't changed. This causes build failures or runtime crashes because the cached binary artifacts are incompatible with the current system libraries.

Proposal

We would like setup-uv to support generating cache keys that include the OS distribution and version (e.g., ubuntu-22.04, macos-13), similar to how ruby/setup-ruby handles it.

ruby/setup-ruby implements robust OS/version detection to prevent this exact issue:
https://github.com/ruby/setup-ruby/blob/8aeb6ff8030dd539317f8e1769a044873b56ea71/common.js#L268

Implementing this in setup-uv would allow users to safely cache compiled artifacts without writing complex, ad-hoc logic to detect the runner environment.

Current limitations

We considered several workarounds to create a unique cache-suffix, but none are ideal:

• matrix.os: Only works for matrix jobs; hard to maintain for single jobs.
• Parsing glibc version: Brittle and difficult to implement reliably across cross-platform shells.
• Env vars (ImageOS): Undocumented and unreliable.