fyn

An extremely fast Python package and project manager, written in Rust.

fyn is an independent community fork of uv. It started on uv's foundation, but it now has its own commands, settings, defaults, and behavior, alongside reduced package-index request metadata, added features, and long-standing bug fixes. See MANIFESTO.md for the full story.

Highlights

• A single tool to replace pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more.
• 10-100x faster than pip.
• Provides comprehensive project management, with a universal lockfile.
• Built-in task runner — define and run project tasks in pyproject.toml.
• Activates virtual environments with fyn shell.
• Upgrades dependencies in one command with fyn upgrade.
• Explains dependency paths with fyn why <package>.
• Runs scripts, with support for inline dependency metadata.
• Installs and manages Python versions.
• Runs and installs tools published as Python packages.
• Includes a pip-compatible interface for a performance boost with a familiar CLI.
• Supports Cargo-style workspaces for scalable projects.
• Disk-space efficient, with a global cache for dependency deduplication.
• Reduced package-index request metadata — compared with upstream uv, fyn sends a minimal fyn/<version> User-Agent header to package indexes such as PyPI, instead of uv/<version> plus the extra LineHaul environment metadata uv included. This reduces what is exposed in that header, but package indexes still receive normal network and request information.
• Supports macOS, Linux, and Windows.

Installation

From PyPI:

# With pip.
pip install fyn

# Or pipx.
pipx install fyn

Or build from source:

cargo install --path crates/fyn

See the command line reference with fyn help.

Documentation

The live docs site is duriantaco.github.io/fyn. The source of truth still lives in docs/ in the repository.

Start here:

• Documentation home
• Getting started
• Working on projects
• Running scripts
• Command reference

For CLI-specific help, use fyn help or fyn help <command>.

Features

Projects

fyn manages project dependencies and environments, with support for lockfiles, workspaces, and more, similar to rye or poetry:

$ fyn init example
Initialized project `example` at `/home/user/example`

$ cd example

$ fyn add ruff
Creating virtual environment at: .venv
Resolved 2 packages in 170ms
Installed 2 packages in 1ms
 + ruff==0.5.0

$ fyn run ruff check
All checks passed!

$ fyn lock
Resolved 2 packages in 0.33ms

$ fyn lock diff
No lockfile changes detected

$ fyn sync
Resolved 2 packages in 0.70ms
Checked 1 package in 0.02ms

Use fyn lock diff to preview how dependency or project metadata edits would change fyn.lock without writing it. The diff reports added, removed, and changed packages, plus metadata-only lockfile updates, which is useful before reviewing or committing a lockfile change.

Task runner

Define tasks in your pyproject.toml and run them with fyn run:

[tool.fyn.tasks]
test = { cmd = "pytest -xvs", env = { PYTHONWARNINGS = "error" } }
lint = "ruff check ."
format = { cmd = "ruff format .", description = "Format code" }
check = { chain = ["lint", "test"], description = "Lint then test" }

$ fyn run test
# runs pytest -xvs

$ fyn run check
# runs lint, then test

$ fyn run test -- -k mytest
# extra args are passed through

$ fyn run --list-tasks
Available tasks:
  check    Lint then test
  format   Format code
  lint     ruff check .
  test     pytest -xvs

Task env values are applied to the spawned command. For chained tasks, parent env values are inherited by child tasks, and child task values take precedence. Extra arguments are supported for cmd tasks, but not for chained tasks.

If fyn run cannot spawn a command, it tries to point you at the next step instead of stopping at a raw OS error: fyn run --list-tasks for likely task typos, fyn tool run <command> for missing Python-provided executables, or a path-specific hint for missing ./script-style commands.

Shell activation

Activate the project's virtual environment in a new shell:

$ fyn shell
success: Activated virtual environment at .venv
Type exit to deactivate.

Works with bash, zsh, fish, nushell, powershell, and cmd.

If you pass a path, fyn shell activates that environment directly. Otherwise it uses VIRTUAL_ENV when set, then the discovered project environment, then a local .venv. Use --no-project to skip project discovery and only check the current directory.

Upgrade dependencies

Upgrade all or specific dependencies in one command:

$ fyn upgrade
info: Upgrading all dependencies...
success: Dependencies upgraded successfully.

$ fyn upgrade requests flask
info: Upgrading: requests, flask
success: Dependencies upgraded successfully.

Supports --dry-run and --no-sync.

fyn upgrade is the convenience form of running fyn lock --upgrade and then fyn sync.

Explain dependencies

Show the project dependency paths that include a package:

$ fyn why numpy
numpy is included because:
project v0.1.0 -> pandas v2.2.1 -> numpy v1.26.4
project v0.1.0 -> scikit-learn v1.4.1.post1 -> scipy v1.12.0 -> numpy v1.26.4

Use --universal to ignore the current platform and Python version, or the dependency group flags such as --group, --only-group, and --no-dev to explain the selected project view.

Project status

Inspect the current project and environment state:

$ fyn status
current directory: /home/user/example
project directory: /home/user/example
managed project: yes
workspace root: /home/user/example
pyproject.toml: yes
fyn.lock: yes
pip-in-project: warn
project environment: /home/user/example/.venv
environment: /home/user/example/.venv
python: /home/user/example/.venv/bin/python3 (3.12.0)

Use --check to fail when obvious project checks do not pass, or --json for scripting and editor integrations. In managed projects, --check also reports missing or mismatched project environments and .python-version pins that do not satisfy requires-python, and prints hint: lines with the suggested fix.

$ fyn status --check
...
check: failed
issue: environment not found
hint: Run `fyn sync` or `fyn venv` to create the project environment.

PyTorch backend diagnosis

Inspect the current machine and environment before installing or reinstalling PyTorch:

$ fyn torch doctor
PyTorch doctor
recommended backend: cu130

next command:
  fyn pip install torch torchvision torchaudio --torch-backend=cu130

Use --json for scripting. fyn torch doctor reports the recommendation and current package state, but does not modify pyproject.toml.

Scripts

fyn manages dependencies and environments for single-file scripts.

Create a new script and add inline metadata declaring its dependencies:

$ echo 'import requests; print(requests.get("https://example.com"))' > example.py

$ fyn add --script example.py requests
Updated `example.py`

Then, run the script in an isolated virtual environment:

$ fyn run example.py
Reading inline script metadata from: example.py
Installed 5 packages in 12ms
<Response [200]>

Tools

fyn executes and installs command-line tools provided by Python packages, similar to pipx.

Run a tool in an ephemeral environment using fynx (an alias for fyn tool run):

$ fynx pycowsay 'hello world!'
Resolved 1 package in 167ms
Installed 1 package in 9ms
  """

  ------------
< hello world! >
  ------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

Install a tool with fyn tool install:

$ fyn tool install ruff
Resolved 1 package in 6ms
Installed 1 package in 2ms
 + ruff==0.5.0
Installed 1 executable: ruff

$ ruff --version
ruff 0.5.0

Python versions

fyn installs Python and allows quickly switching between versions.

Install multiple Python versions:

$ fyn python install 3.12 3.13 3.14
Installed 3 versions in 972ms
 + cpython-3.12.12-macos-aarch64-none
 + cpython-3.13.9-macos-aarch64-none
 + cpython-3.14.0-macos-aarch64-none

Use a specific Python version in the current directory:

$ fyn python pin 3.11
Pinned `.python-version` to `3.11`

Use --python-downloads-json-url <source> when you need fyn python pin to resolve against a custom Python downloads manifest instead of the default bundled metadata.

The pip interface

fyn provides a fast, pip-compatible interface for common pip, pip-tools, and virtualenv workflows.

For many common workflows, you can switch to the fyn pip interface with minimal changes and keep the same overall workflow shape, while getting a 10-100x speedup.

Compile requirements into a platform-independent requirements file:

$ fyn pip compile requirements.in \
   --universal \
   --output-file requirements.txt
Resolved 43 packages in 12ms

Create a virtual environment:

$ fyn venv
Using Python 3.12.3
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

Install the locked requirements:

$ fyn pip sync requirements.txt
Resolved 43 packages in 11ms
Installed 43 packages in 208ms
 + babel==2.15.0
 + certifi==2024.7.4
 ...

Cache size limit

Keep your cache from growing unbounded:

export UV_CACHE_MAX_SIZE=2G

Oldest entries are automatically pruned after every command when the cache exceeds the limit. Supports K, M, G, and T suffixes.

Custom lockfile name

Use different lockfiles for different environments:

UV_LOCKFILE=linux.lock fyn lock
UV_LOCKFILE=macos.lock fyn lock

Private index support

Environment variables work in index URLs — useful for private indexes with credentials:

[[tool.fyn.index]]
name = "private"
url = "https://${PYPI_TOKEN}@pypi.example.com/simple/"

Explicit indexes are also respected for transitive dependencies, so you don't have to list every internal package as a direct dependency.

Migrating from uv

fyn is close to uv, but not a zero-edit rename. Most command-line workflows and UV_* environment variables carry over, but project metadata and lockfile names differ.

# 1. Rename your lockfile
mv uv.lock fyn.lock

# 2. In pyproject.toml, rename [tool.uv] to [tool.fyn]
sed -i 's/\[tool\.uv\]/[tool.fyn]/' pyproject.toml

# 3. Use fyn instead of uv
fyn sync
fyn run pytest
fynx ruff check .

Contributing

We are passionate about supporting contributors of all levels of experience and would love to see you get involved in the project. See the contributing guide to get started.

FAQ

What platforms does fyn support?

The same ones as uv: macOS, Linux, and Windows, across x86_64 and aarch64.

Is fyn compatible with uv?

At the workflow level, often yes, but not as a drop-in replacement. Many commands and UV_* environment variables carry over, but fyn now has fork-specific commands, config, defaults, and behavior. Projects still need [tool.uv] renamed to [tool.fyn] and uv.lock renamed to fyn.lock unless you override the lockfile name.

What's different from uv?

See MANIFESTO.md for the fuller comparison, or the table below for some of the larger user-visible differences:

Acknowledgements

fyn's dependency resolver uses PubGrub under the hood. We're grateful to the PubGrub maintainers, especially Jacob Finkelman, for their support.

fyn started as a fork of uv by Astral and still shares substantial ancestry with it.

Some of fyn's workflow UX, especially around task-running and future workflow ergonomics, has also been informed by Hatch.

fyn's Git implementation is based on Cargo.

Some of fyn's optimizations are inspired by the great work we've seen in pnpm, Orogene, and Bun. We've also learned a lot from Nathaniel J. Smith's Posy and adapted its trampoline for Windows support.

License

fyn is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in fyn by you, as defined in the Apache-2.0 license, shall be dually licensed as above, without any additional terms or conditions.