uvlink 0.4.0

CLI helper for keeping Python venvs outside synced project folders

uvlink

uvlink is a CLI tool that moves .venv folders into a local cache and creates a symlink in your project, so cloud services like Dropbox or iCloud only sync your actual code—not hundreds of megabytes of dependencies.

• Changelog

[!CAUTION] Since v0.4.0, the cache directory changed from ~/.local/share/uvlink/cache/venv/<project-name>-<hash>/venv to ~/.local/share/uvlink/cache/<project-name>-<hash>/<venv_type>. It is recommended to delete existing cached environments created with prior versions and rerun uvlink link to recreate them in the new structure.

Requirements

• Python 3.12+
• macOS or Linux with symlink support

[!WARNING] uvlink is currently only tested on Apple Silicon (M-series) machines running macOS Tahoe. Other operating systems or architectures have not been validated yet.

Install

Using uv tool (recommended)

$ uv tool install uvlink

This installs the CLI into your ~/.local/bin (or platform equivalent) with isolated dependencies handled by Astral's uv.

Using pip

$ pip install uvlink

Quick Start

Navigate to any Python project and run:

$ cd /path/to/your/project
$ uvlink link

This creates a .venv symlink in your project pointing to a cached environment under ~/.local/share/uvlink/cache/<project-name>-<hash>/. Now your cloud service ignores the heavy virtual environment files.

List all linked projects:

$ uvlink ls

Shows all projects having cached environments and whether their symlinks are still linked.

Clean up unlinked caches:

$ uvlink gc

Removes cached environments for projects that no longer have working symlinks, freeing up disk space.

Advanced Usage

uvlink ships with a Typer CLI. Run uvlink --help for all options.

Specify a project directory:

$ uvlink --project-dir /path/to/project link

Works from any location without needing to cd into the project directory first.

Notes

uvlink stores environments under ~/.local/share/uvlink/cache/<project-name>-<hash>/.venv and makes a symlink ./.venv back into that. Each project receives a stable hash based on its absolute path, so repeated runs target the same cache location.

Contributing

Issues and pull requests are welcome. Please keep docstrings and comments in the Google style already used throughout the codebase and run the included linters/formatters before submitting. A pre-commit configuration is provided that runs Ruff and Black; install it with pre-commit install to match formatting.