using uv on nfs or nas shared drives

when using uv with a project located on a shared drive (nfs, nas), you may encounter warnings about file linking. this occurs because uv’s default caching mechanism, hardlinking, is often incompatible with networked filesystems.

this page explains how to configure uv for reliable performance in these environments.

the core problem: filesystem boundaries

by default, uv uses hardlinks to link packages from its global cache into your project’s virtual environment. a hardlink is a direct pointer to data on a disk, making it extremely fast and space-efficient.

however, a fundamental limitation of most operating systems is that hardlinks cannot be created across different filesystems.

when uv tries to create a hardlink from a cache on filesystem-a to a .venv on filesystem-b, the operation fails. this situation is common in several development environments:

• nfs/nas: the project directory is on a network mount, while the uv cache is on the local machine (or vice-versa).
• docker: a project directory is mounted into a container from the host, but the cache is inside the container’s filesystem.
• multiple disks: the cache and project directories are on different physical disks or partitions.

understanding uv’s behavior

when uv fails to create a hardlink, it displays a warning and falls back to a full file copy.

warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance.
         If the cache and target directories are on different filesystems, hardlinking may not be supported.
         If this is intentional, set `export UV_LINK_MODE=copy` or use `--link-mode=copy` to suppress this warning.

while this fallback mechanism is safe, it can sometimes fail, leading to an installation error. explicitly configuring the link mode is the best way to ensure reliability.

solutions and configuration

the recommended approach is to explicitly tell uv which link mode to use, making your project’s configuration robust and silencing the warning.

solution 1: copy (recommended)

this is the most direct and reliable solution for any multi-filesystem environment. it instructs uv to skip the hardlink attempt and go straight to copying files.

you can configure this in two ways:

1. command-line flag: pass the --link-mode=copy flag to your install command.

   terminal bash

   uv pip install --link-mode=copy -r requirements.txt

2. environment variable: set the UV_LINK_MODE environment variable. this is often the most convenient method for configuring a shell or ci/cd environment.

   terminal bash

   export UV_LINK_MODE=copy uv pip install -r requirements.txt

solution 2: symlink (use with caution)

symbolic links (symlinks) are an alternative that works across filesystems and is faster than copying.

however, this method comes with a significant risk: if the uv cache is ever moved or cleared, all symlinked virtual environments will become corrupted and unusable.

due to this risk, symlink is not a default fallback and should only be used if you are certain the cache location is stable.

# configure via flag
uv pip install --link-mode=symlink -r requirements.txt

# configure via environment variable

export UV_LINK_MODE=symlink

external resources

• official uv cli documentation
• github issue: uv falls back to copy instead of symlink
• github issue: nfs cache and lock timeouts