Handle the hard link limit gracefully instead of failing by amol- · Pull Request #17699 · astral-sh/uv

amol- · 2026-01-26T16:59:33Z

Summary

Handle the case where too many hardlinks were created and thus installing packages fails.

There are cases where the file system can have a hardlinks limit and when it's hit uv fails,
for example AWS EFS that has a limit of 177 hard links ( https://docs.aws.amazon.com/efs/latest/ug/troubleshooting-efs-fileop-errors.html#hardlinkerror )

This PR address this by resetting the hardlinks when the limit is reached (it does this by replacing the file in the cache, so new hardlinks can be made)

There can be race conditions over the limit, but those are ok, as the links are reset atomically so in case of race conditions the worst case will be that the limit is reset twice, but nothing will break.

Test Plan

Add a install_hardlink_after_emlink function, it successfully reproduced the issue on my system.
The issue is that it's expensive to run as it has to generate a lot of hardlinks

konstin · 2026-01-26T17:47:44Z

Before making a change, we need a clearer description of the problem. Can you share instructions how to reproduce the problem, as well as the error message you received and the logs? Why do we need an extra option for this, can we handle the better internally?

amol- · 2026-01-26T18:17:14Z

Before making a change, we need a clearer description of the problem
Can you share instructions how to reproduce the problem,

As explained in the description you can reproduce this by using EFS and installing a package in more than 177 python environments. That's probably the easiest way.

as well as the error message you received and the logs?

You would get an error like

2026/01/06 09:01:25.755055774       XXXX/archive-v0/XCaM_31VGMkcLZe9KeK-L/pkg_resources/__init__.py
2026/01/06 09:01:25.755067836       to
2026/01/06 09:01:25.755068532       YYYY/builds-v0/.tmp5VSfaw/lib/python3.14/site-packages/pkg_resources/__init__.py:
2026/01/06 09:01:25.755077725       Too many links (os error 31)

Why do we need an extra option for this, can we handle the better internally?

I think we can detect the os error and handle it automatically, but I wasn't very fond of introducing an install bottleneck without the user being aware of it. Adding an explicit option seemed to ensure that the user was aware the bottleneck was there. But I'm happy to change to automatic handling of the error if you feel it's an approach more aligned to uv user experience

EliteTK · 2026-01-26T19:14:16Z

Rather than having the user figure out the hard link limit and specify it themselves, we should just handle EMLINK and ERROR_TOO_MANY_LINKS gracefully.

Moreover, I believe we don't lock the cache for exclusive access in these cases, so there's a chance that two instances of uv end up copying the file at the same time. But the way this is written, this won't cause any corruption, just a bit of unnecessary work.

amol- · 2026-01-26T19:40:21Z

Rather than having the user figure out the hard link limit and specify it themselves, we should just handle EMLINK and ERROR_TOO_MANY_LINKS gracefully.

Moreover, I believe we don't lock the cache for exclusive access in these cases, so there's a chance that two instances of uv end up copying the file at the same time. But the way this is written, this won't cause any corruption, just a bit of unnecessary work.

Sounds good! I'll move the implementation in that direction and I'll create a script to reproduce the issue to verify it, as it's not as easy as before to reproduce the condition at that point.

amol- · 2026-01-27T10:23:54Z

The test is flagged as passed in the CI

PASS [   1.137s] (1749/3484) uv::it pip_sync::install_hardlink_after_emlink

But I don't know if we have a way to see if it was skipped or not because the logging isn't shown.

PS: On my system I know it's not skipped and works as expected, I can see that via the logging

amol- · 2026-02-06T16:27:42Z

@EliteTK anything I can do to help with this PR? I have to manually cleanup links one on of our systems once in a while when the deploy fails, so I'd love to see this one go

EliteTK · 2026-02-06T18:51:40Z

@amol- Sorry, I just hadn't gotten around to re-reviewing it yet. But I should be able to do that next week.

mconflitti-pbc · 2026-02-13T18:59:18Z

@EliteTK thanks for reviewing this! Any updates on when you think you will have some bandwidth to finish taking a look?

EliteTK

Are there any other places where we make a hardlink where we should instead be calling this?

crates/uv-install-wheel/src/linker.rs

crates/uv/tests/it/pip_sync.rs

amol- · 2026-02-21T15:23:43Z

@EliteTK I still plan to move this forward. I'm just stuck with limited internet connectivity until next week. Then I'll address your suggestions

amol- · 2026-02-26T16:37:09Z

moving this back to a draft until I finished addressing review comments

…phase

amol- · 2026-02-27T14:46:44Z

.github/workflows/test.yml

+      - name: "Create minix filesystem (low hardlink limit)"
+        run: |
+          truncate -s 16M /tmp/minix.img
+          mkfs.minix /tmp/minix.img


I went for minix because it has a limit of 250 hard links, thus makes the test faster to run

amol- · 2026-02-27T14:48:23Z

@EliteTK I rebased against main, addressed your comments and made the test run faster and more predictably via a dedicated file system. It should now be ready for re-review

EliteTK · 2026-02-27T16:05:02Z

This is looking pretty great actually! Thanks.

I'll try to review this properly soonish (probably Monday at this rate) but just a quick thing i noticed. We should still set UV_INTERNAL__TEST_MAXLINKS_FS for testing on windows, it can just be the default NTFS. But this is definitely the right way to approach testing this!

amol- · 2026-02-27T18:10:47Z

We should still set UV_INTERNAL__TEST_MAXLINKS_FS for testing on windows, it can just be the default NTFS. But this is definitely the right way to approach testing this!

Added the setup for windows too, the CI seems to confirm it worked -> https://github.com/astral-sh/uv/actions/runs/22497686685/job/65176453709?pr=17699#step:11:1597 + https://github.com/astral-sh/uv/actions/runs/22497686685/job/65176453709?pr=17699#step:11:31

EliteTK

Looks good, there's a couple of small things. I can probably just nip them myself tomorrow, but feel free to address them yourself.

crates/uv-fs/src/link.rs

EliteTK · 2026-03-03T23:50:10Z

crates/uv-fs/src/link.rs

+                "Resetting cache entry due to too many hardlinks: {}",
+                src.display()
+            );
+            let parent = src.parent().ok_or_else(|| {


Should probably also handle src.parent() returning an empty path (indicating it was passed a single component relative path).

I'm a bit confused by this one, I'd expect that the installed file is always in a package, like /home/user/.cache/uv/.../package-1.0/file.py so not clear when src.parent() could not exist.

But I guess it won't cause any harm handling an mpty parent,
c72de08 should handle both the case of invalid parents (like a parent for /) and the case of missing parents. Both will lead to "current directory"

.github/workflows/test.yml

crates/uv-fs/src/link.rs

crates/uv-static/src/env_vars.rs

Co-authored-by: Tomasz Kramkowski <tomasz@kramkow.ski>

amol- · 2026-03-04T14:23:10Z

@EliteTK it smells like the CI failures are transient errors, do you have a chance to rerun the CI? I don't have the option available

amol- · 2026-03-05T18:10:53Z

my last commit yesterday restarted the tests, but they failed again with 401 on requests to setup build infrastructure, not sure if there is a way I can intervene

Error: failed to solve: dhi.io/alpine-base:3.23: failed to resolve source metadata for dhi.io/alpine-base:3.23: failed to authorize: failed to fetch anonymous token: unexpected status: 401 Unauthorized
Error: failed with: Error: failed to solve: dhi.io/alpine-base:3.23: failed to resolve source metadata for dhi.io/alpine-base:3.23: failed to authorize: failed to fetch anonymous token: unexpected status: 401 Unauthorized

EliteTK · 2026-03-05T19:58:24Z

Those are apparently because as an external contributor your CI runs don't get the creds required for those...

So you can just ignore them, I guess once this hits main if there is an issue then it can be reverted.

Other than that, PR looks good. I was wrong about needing to copy the permissions, thought the code wrote into the tempfile rather than overwriting with copy. We discussed internally what path we would want for that windows test.

I didn't want to waste your time on these last couple of things so I pushed a commit. Will merge this once the rest of CI passes.

amol- · 2026-03-06T15:20:52Z

@EliteTK thanks for all the support in getting this one through. I really appreciated your help!

EliteTK · 2026-03-06T16:08:52Z

@amol- thanks for the contribution :)

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [uv](https://github.com/astral-sh/uv) | patch | `0.10.7` → `0.10.9` | 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 (uv)</summary> ### [`v0.10.9`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0109) [Compare Source](astral-sh/uv@0.10.8...0.10.9) Released on 2026-03-06. ##### Enhancements - Add `fbgemm-gpu`, `fbgemm-gpu-genai`, `torchrec`, and `torchtune` to the PyTorch list ([#18338](astral-sh/uv#18338)) - Add torchcodec to PyTorch List ([#18336](astral-sh/uv#18336)) - Log the duration we took before erroring ([#18231](astral-sh/uv#18231)) - Warn when using `uv_build` settings without `uv_build` ([#15750](astral-sh/uv#15750)) - Add fallback to `/usr/lib/os-release` on Linux system lookup failure ([#18349](astral-sh/uv#18349)) - Use `cargo auditable` to include SBOM in uv builds ([#18276](astral-sh/uv#18276)) ##### Configuration - Add an environment variable for `UV_VENV_RELOCATABLE` ([#18331](astral-sh/uv#18331)) ##### Performance - Avoid toml `Document` overhead ([#18306](astral-sh/uv#18306)) - Use a single global workspace cache ([#18307](astral-sh/uv#18307)) ##### Bug fixes - Continue on trampoline job assignment failures ([#18291](astral-sh/uv#18291)) - Handle the hard link limit gracefully instead of failing ([#17699](astral-sh/uv#17699)) - Respect build constraints for workspace members ([#18350](astral-sh/uv#18350)) - Revalidate editables and other dependencies in scripts ([#18328](astral-sh/uv#18328)) - Support Python 3.13+ on Android ([#18301](astral-sh/uv#18301)) - Support `cp3-none-any` ([#17064](astral-sh/uv#17064)) - Skip tool environments with broken links to Python on Windows ([#17176](astral-sh/uv#17176)) ##### Documentation - Add documentation for common marker values ([#18327](astral-sh/uv#18327)) - Improve documentation on virtual dependencies ([#18346](astral-sh/uv#18346)) ### [`v0.10.8`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0108) [Compare Source](astral-sh/uv@0.10.7...0.10.8) Released on 2026-03-03. ##### Python - Add CPython 3.10.20 - Add CPython 3.11.15 - Add CPython 3.12.13 ##### Enhancements - Add Docker images based on Docker Hardened Images ([#18247](astral-sh/uv#18247)) - Add resolver hint when `--exclude-newer` filters out all versions of a package ([#18217](astral-sh/uv#18217)) - Configure a real retry minimum delay of 1s ([#18201](astral-sh/uv#18201)) - Expand `uv_build` direct build compatibility ([#17902](astral-sh/uv#17902)) - Fetch CPython from an Astral mirror by default ([#18207](astral-sh/uv#18207)) - Download uv releases from an Astral mirror in installers by default ([#18191](astral-sh/uv#18191)) - Add SBOM attestations to Docker images ([#18252](astral-sh/uv#18252)) - Improve hint for installing meson-python when missing as build backend ([#15826](astral-sh/uv#15826)) ##### Configuration - Add `UV_INIT_BARE` environment variable for `uv init` ([#18210](astral-sh/uv#18210)) ##### Bug fixes - Prevent `uv tool upgrade` from installing excluded dependencies ([#18022](astral-sh/uv#18022)) - Promote authentication policy when saving tool receipts ([#18246](astral-sh/uv#18246)) - Respect exclusions in scripts ([#18269](astral-sh/uv#18269)) - Retain default-branch Git SHAs in `pylock.toml` files ([#18227](astral-sh/uv#18227)) - Skip installed Python check for URL dependencies ([#18211](astral-sh/uv#18211)) - Respect constraints during `--upgrade` ([#18226](astral-sh/uv#18226)) - Fix `uv tree` orphaned roots and premature deduplication ([#17212](astral-sh/uv#17212)) ##### Documentation - Mention cooldown and tweak inline script metadata in dependency bots documentation ([#18230](astral-sh/uv#18230)) - Move cache prune in GitLab to `after_script` ([#18206](astral-sh/uv#18206)) </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).

amol- changed the title ~~Add the --link-limit and UV_LINK_LIMIT options and handle limit~~ Handle TooManyLinks by resetting the hard links when it's hit Jan 26, 2026

amol- changed the title ~~Handle TooManyLinks by resetting the hard links when it's hit~~ Handle TooManyLinks by resetting the hard links when hit Jan 26, 2026

amol- marked this pull request as ready for review January 27, 2026 10:24

EliteTK self-requested a review February 4, 2026 10:59

EliteTK reviewed Feb 14, 2026

View reviewed changes

amol- marked this pull request as draft February 26, 2026 16:36

reset hardlinks count when reaching maximum hardlinks during install …

8312db4

…phase

amol- force-pushed the cache-reset-links branch from d78580e to 8312db4 Compare February 27, 2026 09:57

ops, fix env var name

9aa6873

amol- force-pushed the cache-reset-links branch from fb47ea2 to 9aa6873 Compare February 27, 2026 14:34

amol- commented Feb 27, 2026

View reviewed changes

amol- marked this pull request as ready for review February 27, 2026 14:47

EliteTK self-requested a review February 27, 2026 16:05

test on windows too

21703ca

EliteTK reviewed Mar 3, 2026

View reviewed changes

EliteTK reviewed Mar 4, 2026

View reviewed changes

crates/uv-fs/src/link.rs Show resolved Hide resolved

use debug and set permissions

83490e7

EliteTK reviewed Mar 4, 2026

View reviewed changes

crates/uv-static/src/env_vars.rs Outdated Show resolved Hide resolved

amol- and others added 2 commits March 4, 2026 14:51

Better handle parent corner cases

c72de08

Update crates/uv-static/src/env_vars.rs

fd63bb6

Co-authored-by: Tomasz Kramkowski <tomasz@kramkow.ski>

rename the low links environment variable

6f8a936

Some reshuffling/cleanup

7d63874

EliteTK approved these changes Mar 5, 2026

View reviewed changes

EliteTK changed the title ~~Handle TooManyLinks by resetting the hard links when hit~~ Handle the hard link limit gracefully instead of failing Mar 5, 2026

EliteTK added the bug Something isn't working label Mar 5, 2026

EliteTK merged commit 6036575 into astral-sh:main Mar 5, 2026
232 of 244 checks passed

BrewTestBot mentioned this pull request Mar 7, 2026

uv 0.10.9 Homebrew/homebrew-core#271033

Merged

Conversation

amol- commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test Plan

Uh oh!

konstin commented Jan 26, 2026

Uh oh!

amol- commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

EliteTK commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

amol- commented Jan 26, 2026

Uh oh!

amol- commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

amol- commented Feb 6, 2026

Uh oh!

EliteTK commented Feb 6, 2026

Uh oh!

mconflitti-pbc commented Feb 13, 2026

Uh oh!

EliteTK left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

amol- commented Feb 21, 2026

Uh oh!

amol- commented Feb 26, 2026

Uh oh!

amol- Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

amol- commented Feb 27, 2026

Uh oh!

EliteTK commented Feb 27, 2026

Uh oh!

amol- commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

EliteTK left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

EliteTK Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

amol- Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

amol- commented Mar 4, 2026

Uh oh!

amol- commented Mar 5, 2026

Uh oh!

EliteTK commented Mar 5, 2026

Uh oh!

Uh oh!

amol- commented Mar 6, 2026

Uh oh!

EliteTK commented Mar 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

amol- commented Jan 26, 2026 •

edited

Loading

amol- commented Jan 26, 2026 •

edited

Loading

EliteTK commented Jan 26, 2026 •

edited

Loading

amol- commented Jan 27, 2026 •

edited

Loading

amol- commented Feb 27, 2026 •

edited

Loading