uv-fs

crates/uv-fs/ is uv's filesystem helper crate. It wraps fs-err with locked-file primitives, atomic writes, simplified path display, and tokio-friendly streaming readers.

Purpose

uv touches the filesystem constantly — caches, lockfiles, venvs, sdists, generated .pyc files. Centralizing the wrappers in one crate lets the rest of the workspace ignore the platform differences and the error-message conventions.

Key abstractions

• LockedFile — cross-platform exclusive / shared file lock.
• LockedFileMode — Exclusive / Shared.
• LockedFileError — errors specific to lock acquisition.
• Simplified extension trait — path.user_display() to render paths relative to $HOME or the current directory.
• write_atomic — atomically write a file via temp-file + rename.
• cachedir, directories — helpers for creating cache-style directories with the CACHEDIR.TAG marker.
• PythonExt — extension methods used when introspecting Python paths.
• ProgressReader — wraps an AsyncRead for upload/download progress reporting.
• CWD — a LazyLock<PathBuf> for the resolved current working directory, used so we consistently work with an absolute path.

See also

• uv-cache for the heaviest user.
• uv-publish uses ProgressReader for upload progress.