Summary

uv pip compile seems to ignore required-environments, which differs in behavior from uv lock

Let's use hdbscan as our test subject. It does not publish Linux ARM wheels for Python 3.12. If we have this pyproject.toml, where we add Python 3.12 Linux ARM to required-environments and use no-build = true:

[project]
name = "test"
version = "0.0.1"
requires-python = ">=3.12"
dependencies = ["hdbscan==0.8.42"]

[tool.uv]
no-build = true
required-environments = [
  "python_version == '3.12' and sys_platform == 'linux' and platform_machine == 'aarch64'",
]

We can see that:

• uv pip compile + required-environments runs without an error (unexpected)

  > uv pip compile --generate-hashes --no-annotate --no-header --no-deps --universal
  
  hdbscan==0.8.42 \
      --hash=sha256:1459d777d16800361b504656982ae3988fc412b97a8f244ffbd565c72a39ca41 \
      --hash=sha256:2ab4c7fba52f648fe4276d7b60f6831a9009089872a5ca05f91d6ed1bbe52d23 \
      --hash=sha256:2c86d215b5940a5414ceb468af5987941d3526e49d09418296830528161ccdd6 \
      --hash=sha256:31541afa4ce2d42ad828ffd5da1bf40d8212fa8318cc28e58c65ffe719e9083b \
      --hash=sha256:3bd749a3df39c7e965bd8b2173c3804cdb11ad73d524a5df1201360814293614 \
      --hash=sha256:7e0f160ee0d5e61d9a2411c44fa41c12849e814899851cab8e17e924487018e1 \
      --hash=sha256:990b9f9ce14f290eb8bd9343048cb50b890560de99ced4fb31c486cb0c9f0f74 \
      --hash=sha256:bc428bff42b9ec8ecbaf5d790b6b6de9e2cb120059350d0caecb92311f44b869 \
      --hash=sha256:cd86e30bfe1f1363b9b97a8a84cbeebf761c5ff4262037f9cf0d068b590fe541 \
      --hash=sha256:e14d7309c91e1a59f592936555fe4282e66061719225d9cb2d7bf18040bb8b54 \
      --hash=sha256:f0cc0f279f0f83203277fb5b09422cbfab577fe269e3f71d0082354f65d71cf3 \
      --hash=sha256:f265f1ae267713c7a8dfa14ddc530c1ccf87905cf003db65769b9afed519d910 \
      --hash=sha256:fd9f0d5f65a5aa4437b8f69ff8cb4ae6d42723e543254dca49c62f02192c2791

• uv lock + required-environments errors (expected)

  > uv lock
  Using CPython 3.12.13
    × No solution found when resolving dependencies for split (markers: python_full_version == '3.12.*' and platform_machine == 'aarch64' and sys_platform == 'linux'):
    ╰─▶ Because hdbscan==0.8.42 has no `python_full_version == '3.12.*' and platform_machine == 'aarch64' and sys_platform == 'linux'`-compatible wheels and your project depends on
        hdbscan==0.8.42, we can conclude that your project's requirements are unsatisfiable.
  
        hint: The resolution failed for an environment that is not the current one, consider limiting the environments with `tool.uv.environments`.

If we instead use environments

[project]
name = "test"
version = "0.0.1"
requires-python = ">=3.12"
dependencies = ["hdbscan==0.8.42"]

[tool.uv]
no-build = true
environments = [
  "python_version == '3.12' and sys_platform == 'linux' and platform_machine == 'aarch64'",
]

• uv pip compile + environments does error

  > uv pip compile --generate-hashes --no-annotate --no-header --no-deps --universal
  × No solution found when resolving dependencies for split (markers: python_full_version == '3.12.*' and platform_machine == 'aarch64' and sys_platform == 'linux'):
    ╰─▶ Because hdbscan==0.8.42 has no `python_full_version == '3.12.*' and platform_machine == 'aarch64' and sys_platform == 'linux'`-compatible wheels and you require hdbscan==0.8.42, we
        can conclude that your requirements are unsatisfiable.
  
        hint: The resolution failed for an environment that is not the current one, consider limiting the environments with `tool.uv.environments`.

This seems backwards to me, based on the docs:

https://docs.astral.sh/uv/reference/settings/#required-environments

By default, uv requires each package to include at least one wheel that is compatible with the designated Python version. The required-environments setting can be used to ensure that the resulting resolution contains wheels for specific platforms, or fails if no such wheels are available.

While the environments setting limits the set of environments that uv will consider when resolving dependencies, required-environments expands the set of platforms that uv must support when resolving dependencies.

Platform

Darwin 25.4.0 arm64

Version

uv 0.11.13 (4512a39 2026-05-10 aarch64-apple-darwin)

Python version

3.12