uv falls back to copy instead of symlink

[ypnos]

When using a Docker cache mount, as recommended in the documentation, uv falls back to copying instead of hardlinking and complains about it. The message also recommends to suppress the complaint with explicitely setting the link mode to COPY.

See

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

Line 443 in fe4e39a

warn_user_once!("Failed to clone files; falling back to full copy. This may lead to degraded performance.\n If the cache and target directories are on different filesystems, reflinking may not be supported.\n If this is intentional, set `export UV_LINK_MODE=copy` or use `--link-mode=copy` to suppress this warning.");

As a matter of fact, uv now supports link mode "symlink".

1. It would probably be great to try symlink before falling back to copy
2. The error message makes it sound like we have to live with the performance degradation, and does not mention that symlink mode is also available
3. The Docker documentation should include ENV UV_LINK_MODE=symlink so that people do not run into this issue. See https://docs.astral.sh/uv/guides/integration/docker/#caching

[charliermarsh]

Symlinks are fairly problematic, since if the cache gets deleted, your entire project will break. I generally would not want to default to them.

[zanieb]

We set copy in the example at https://github.com/astral-sh/uv-docker-example/blob/3d2a5afd814babec58804b9ffce923ea114a76fb/Dockerfile#L10-L11 — needs to be updated over here.

[notatallshaw]

Symlinks are fairly problematic, since if the cache gets deleted, your entire project will break. I generally would not want to default to them.

I use symlink mode at work and I agree with this, I've hit an issue twice where I had to recreate my entire environment, for me it's worth the trade off but I think a user should know they are opting into symlink.

[charliermarsh]

I think this is the correct behavior. It's totally fine for users to use symlinks, but they are also dangerous so I'd prefer not to make them the default.