CLI Reference

fyn

An extremely fast Python package and project manager.

Usage

fyn [OPTIONS] <COMMAND>

Commands

fyn auth

Manage authentication

fyn run

Run a command or script

fyn init

Create a new project

fyn add

Add dependencies to the project

fyn remove

Remove dependencies from the project

fyn version

Read or update the project's version

fyn sync

Update the project's environment

fyn lock

Update the project's lockfile

fyn upgrade

Upgrade project dependencies

fyn export

Export the project's lockfile to an alternate format

fyn tree

Display the project's dependency tree

fyn format

Format Python code in the project

fyn audit

Audit the project's dependencies

fyn tool

Run and install commands provided by Python packages

fyn python

Manage Python versions and installations

fyn pip

Manage Python packages directly in an environment

fyn torch

Diagnose PyTorch backend selection for the current machine

fyn venv

Create a virtual environment

fyn shell

Activate the virtual environment in a new shell

fyn build

Build Python packages into source distributions and wheels

fyn publish

Upload distributions to an index

fyn cache

Manage fyn's cache

fyn status

Show the current project and environment status

fyn self

Manage the fyn executable

fyn help

Display documentation for a command

fyn auth

Manage authentication

Usage

fyn auth [OPTIONS] <COMMAND>

Commands

fyn auth login

Login to a service

fyn auth logout

Logout of a service

fyn auth token

Show the authentication token for a service

fyn auth dir

Show the path to the fyn credentials directory

fyn auth login

Login to a service

Usage

fyn auth login [OPTIONS] <SERVICE>

Arguments

SERVICE

The domain or URL of the service to log into

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--keyring-provider keyring-provider

The keyring provider to use for storage of credentials.

Only --keyring-provider native is supported for login, which uses the system keyring via an integration built into fyn.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--password password

The password to use for the service.

Use - to read the password from stdin.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--token, -t token

The token to use for the service.

The username will be set to __token__.

Use - to read the token from stdin.

--username, -u username

The username to use for the service

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn auth logout

Logout of a service

Usage

fyn auth logout [OPTIONS] <SERVICE>

Arguments

SERVICE

The domain or URL of the service to logout from

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--keyring-provider keyring-provider

The keyring provider to use for storage of credentials.

Only --keyring-provider native is supported for logout, which uses the system keyring via an integration built into fyn.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--username, -u username

The username to logout

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn auth token

Show the authentication token for a service

Usage

fyn auth token [OPTIONS] <SERVICE>

Arguments

SERVICE

The domain or URL of the service to lookup

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--keyring-provider keyring-provider

The keyring provider to use for reading credentials

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--username, -u username

The username to lookup

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn auth dir

Show the path to the fyn credentials directory.

By default, credentials are stored in the fyn data directory at $XDG_DATA_HOME/fyn/credentials or $HOME/.local/share/fyn/credentials on Unix and %APPDATA%\fyn\data\credentials on Windows.

The credentials directory may be overridden with $UV_CREDENTIALS_DIR.

Credentials are only stored in this directory when the plaintext backend is used, as opposed to the native backend, which uses the system keyring.

Usage

fyn auth dir [OPTIONS] [SERVICE]

Arguments

SERVICE

The domain or URL of the service to lookup

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn run

Run a command or script.

Ensures that the command runs in a Python environment.

When used with a file ending in .py or an HTTP(S) URL, the file will be treated as a script and run with a Python interpreter, i.e., fyn run file.py is equivalent to fyn run python file.py. For URLs, the script is temporarily downloaded before execution. If the script contains inline dependency metadata, it will be installed into an isolated, ephemeral environment. When used with -, the input will be read from stdin, and treated as a Python script.

When used in a project, the project environment will be created and updated before invoking the command.

When used outside a project, if a virtual environment can be found in the current directory or a parent directory, the command will be run in that environment. Otherwise, the command will be run in the environment of the discovered interpreter.

By default, the project or workspace is discovered from the current working directory. However, when using --preview-features target-workspace-discovery, the project or workspace is instead discovered from the target script's directory.

Arguments following the command (or script) are not interpreted as arguments to fyn. All options to fyn must be provided before the command, e.g., fyn run --verbose foo. A -- can be used to separate the command from fyn options for clarity, e.g., fyn run --python 3.12 -- python.

Usage

fyn run [OPTIONS] [COMMAND]

Options

--active

Prefer the active virtual environment over the project's virtual environment.

If the project virtual environment is active or no virtual environment is active, this has no effect.

--all-extras

Include all optional dependencies.

This option is only available when running in a project.

--all-groups

Include dependencies from all dependency groups.

--no-group can be used to exclude specific groups.

--all-packages

Run the command with all workspace members installed.

The workspace's environment (.venv) is updated to include all workspace members.

Any extras or groups specified via --extra, --group, or related options will be applied to all workspace members.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--compile-bytecode, --compile

Compile Python files to bytecode after installation.

By default, fyn does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, fyn will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

May also be set with the UV_COMPILE_BYTECODE environment variable.

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--env-file env-file

Load environment variables from a .env file.

Can be provided multiple times, with subsequent files overriding values defined in previous files.

May also be set with the UV_ENV_FILE environment variable.

--exact

Perform an exact sync, removing extraneous packages.

When enabled, fyn will remove any extraneous packages from the environment. By default, fyn run will make the minimum necessary changes to satisfy the requirements.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra extra

Include optional dependencies from the specified extra name.

May be provided more than once.

This option is only available when running in a project.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--frozen

Run without updating the fyn.lock file [env: UV_FROZEN=]

Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, fyn will exit with an error. If the pyproject.toml includes changes to dependencies that have not been included in the lockfile yet, they will not be present in the environment.

--group group

Include dependencies from the specified dependency group.

May be provided multiple times.

--gui-script

Run the given path as a Python GUI script.

Using --gui-script will attempt to parse the path as a PEP 723 script and run it with pythonw.exe, irrespective of its extension. Only available on Windows.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--isolated

Run the command in an isolated virtual environment [env: UV_ISOLATED=]

Usually, the project environment is reused for performance. This option forces a fresh environment to be used for the project, enforcing strict isolation between dependencies and declaration of requirements.

An editable installation is still used for the project.

When used with --with or --with-requirements, the additional dependencies will still be layered in a second environment.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--list-tasks

List available tasks defined in [tool.fyn.tasks] and exit

--locked

Assert that the fyn.lock will remain unchanged [env: UV_LOCKED=]

Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, fyn will exit with an error.

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--module, -m

Run a Python module.

Equivalent to python -m <module>.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

May also be set with the UV_NO_BINARY environment variable.

--no-binary-package no-binary-package

Don't install pre-built wheels for a specific package

May also be set with the UV_NO_BINARY_PACKAGE environment variable.

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

May also be set with the UV_NO_BUILD environment variable.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-build-package no-build-package

Don't build source distributions for a specific package

May also be set with the UV_NO_BUILD_PACKAGE environment variable.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-default-groups

Ignore the default dependency groups.

fyn includes the groups defined in tool.fyn.default-groups by default. This disables that option, however, specific groups can still be included with --group.

May also be set with the UV_NO_DEFAULT_GROUPS environment variable.

--no-dev

Disable the development dependency group [env: UV_NO_DEV=]

This option is an alias of --no-group dev. See --no-default-groups to disable all default groups instead.

This option is only available when running in a project.

--no-editable

Install any editable dependencies, including the project and any workspace members, as non-editable [env: UV_NO_EDITABLE=]

--no-env-file

Avoid reading environment variables from a .env file [env: UV_NO_ENV_FILE=]

--no-extra no-extra

Exclude the specified optional dependencies, if --all-extras is supplied.

May be provided multiple times.

--no-group no-group

Disable the specified dependency group.

This option always takes precedence over default groups, --all-groups, and --group.

May be provided multiple times.

May also be set with the UV_NO_GROUP environment variable.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-project, --no_workspace

Avoid discovering the project or workspace.

Instead of searching for projects in the current directory and parent directories, run in an isolated, ephemeral environment populated by the --with requirements.

If a virtual environment is active or found in a current or parent directory, it will be used as if there was no project or workspace.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--no-sync

Avoid syncing the virtual environment [env: UV_NO_SYNC=]

Implies --frozen, as the project dependencies will be ignored (i.e., the lockfile will not be updated, since the environment will not be synced regardless).

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--only-dev

Only include the development dependency group.

The project and its dependencies will be omitted.

This option is an alias for --only-group dev. Implies --no-default-groups.

--only-group only-group

Only include dependencies from the specified dependency group.

The project and its dependencies will be omitted.

May be provided multiple times. Implies --no-default-groups.

--package package

Run the command in a specific package in the workspace.

If the workspace member does not exist, fyn will exit with an error.

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to use for the run environment.

If the interpreter request is satisfied by a discovered environment, the environment will be used.

See fyn python to view supported request formats.

May also be set with the UV_PYTHON environment variable.

--python-platform python-platform

The platform for which requirements should be installed.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.

WARNING: When specified, fyn will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.

Possible values:

• windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
• linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
• macos: An alias for aarch64-apple-darwin, the default target for macOS
• x86_64-pc-windows-msvc: A 64-bit x86 Windows target
• aarch64-pc-windows-msvc: An ARM64 Windows target
• i686-pc-windows-msvc: A 32-bit x86 Windows target
• x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
• aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
• x86_64-apple-darwin: An x86 macOS target
• aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
• aarch64-unknown-linux-musl: An ARM64 Linux target
• x86_64-unknown-linux-musl: An x86_64 Linux target
• riscv64-unknown-linux: A RISCV64 Linux target
• x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
• x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
• x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
• x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
• x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
• x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
• x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
• x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
• x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
• x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
• x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
• x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
• x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
• aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
• aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
• aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
• aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
• aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
• aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
• aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
• aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
• aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
• aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
• aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
• aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
• aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
• aarch64-linux-android: An ARM64 Android target
• x86_64-linux-android: An x86_64 Android target
• wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
• arm64-apple-ios: An ARM64 target for iOS device
• arm64-apple-ios-simulator: An ARM64 target for iOS simulator
• x86_64-apple-ios-simulator: An x86_64 target for iOS simulator

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall, --force-reinstall

Reinstall all packages, regardless of whether they're already installed. Implies --refresh

--reinstall-package reinstall-package

Reinstall a specific package, regardless of whether it's already installed. Implies --refresh-package

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--script, -s

Run the given path as a Python script.

Using --script will attempt to parse the path as a PEP 723 script, irrespective of its extension.

--upgrade, -U

Allow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh

--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

--with, -w with

Run with the given packages installed.

When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.

--with-editable with-editable

Run with the given packages installed in editable mode.

When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.

--with-requirements with-requirements

Run with the packages listed in the given files.

The following formats are supported: requirements.txt, .py files with inline metadata, and pylock.toml.

The same environment semantics as --with apply.

Using pyproject.toml, setup.py, or setup.cfg files is not allowed.

fyn init

Create a new project.

Follows the pyproject.toml specification.

If a pyproject.toml already exists at the target, fyn will exit with an error.

If a pyproject.toml is found in any of the parent directories of the target path, the project will be added as a workspace member of the parent.

Some project state is not created until needed, e.g., the project virtual environment (.venv) and lockfile (fyn.lock) are lazily created during the first sync.

Usage

fyn init [OPTIONS] [PATH]

Arguments

PATH

The path to use for the project/script.

Defaults to the current working directory when initializing an app or library; required when initializing a script. Accepts relative and absolute paths.

If a pyproject.toml is found in any of the parent directories of the target path, the project will be added as a workspace member of the parent, unless --no-workspace is provided.

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--app, --application

Create a project for an application.

This is the default behavior if --lib is not requested.

This project kind is for web servers, scripts, and command-line interfaces.

By default, an application is not intended to be built and distributed as a Python package. The --package option can be used to create an application that is distributable, e.g., if you want to distribute a command-line interface via PyPI.

--author-from author-from

Fill in the authors field in the pyproject.toml.

By default, fyn will attempt to infer the author information from some sources (e.g., Git) (auto). Use --author-from git to only infer from Git configuration. Use --author-from none to avoid inferring the author information.

Possible values:

• auto: Fetch the author information from some sources (e.g., Git) automatically
• git: Fetch the author information from Git configuration only
• none: Do not infer the author information

--bare

Only create a pyproject.toml.

Disables creating extra files like README.md, the src/ tree, .python-version files, etc.

When combined with --script, the script will only contain the inline metadata header.

--build-backend build-backend

Initialize a build-backend of choice for the project.

Implicitly sets --package.

May also be set with the UV_INIT_BUILD_BACKEND environment variable.

Possible values:

• uv: Use uv as the project build backend
• hatch: Use hatchling as the project build backend
• flit: Use flit-core as the project build backend
• pdm: Use pdm-backend as the project build backend
• poetry: Use poetry-core as the project build backend
• setuptools: Use setuptools as the project build backend
• maturin: Use maturin as the project build backend
• scikit: Use scikit-build-core as the project build backend

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--description description

Set the project description

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--lib, --library

Create a project for a library.

A library is a project that is intended to be built and distributed as a Python package.

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--name name

The name of the project.

Defaults to the name of the directory.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-description

Disable the description for the project

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-package

Do not set up the project to be built as a Python package.

Does not include a [build-system] for the project.

This is the default behavior when using --app.

--no-pin-python

Do not create a .python-version file for the project.

By default, fyn will create a .python-version file containing the minor version of the discovered Python interpreter, which will cause subsequent fyn commands to use that version.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-readme

Do not create a README.md file

--no-workspace, --no-project

Avoid discovering a workspace and create a standalone project.

By default, fyn searches for workspaces in the current directory or any parent directory.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--package

Set up the project to be built as a Python package.

Defines a [build-system] for the project.

This is the default behavior when using --lib or --build-backend.

When using --app, this will include a [project.scripts] entrypoint and use a src/ project structure.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to use to determine the minimum supported Python version.

See fyn python to view supported request formats.

May also be set with the UV_PYTHON environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--script

Create a script.

A script is a standalone file with embedded metadata enumerating its dependencies, along with any Python version requirements, as defined in the PEP 723 specification.

PEP 723 scripts can be executed directly with fyn run.

By default, adds a requirement on the system Python version; use --python to specify an alternative Python version requirement.

--vcs vcs

Initialize a version control system for the project.

By default, fyn will initialize a Git repository (git). Use --vcs none to explicitly avoid initializing a version control system.

Possible values:

• git: Use Git for version control
• none: Do not use any version control system

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn add

Add dependencies to the project.

Dependencies are added to the project's pyproject.toml file.

If a given dependency exists already, it will be updated to the new version specifier unless it includes markers that differ from the existing specifier in which case another entry for the dependency will be added.

The lockfile and project environment will be updated to reflect the added dependencies. To skip updating the lockfile, use --frozen. To skip updating the environment, use --no-sync.

If any of the requested dependencies cannot be found, fyn will exit with an error, unless the --frozen flag is provided, in which case fyn will add the dependencies verbatim without checking that they exist or are compatible with the project.

fyn will search for a project in the current directory or any parent directory. If a project cannot be found, fyn will exit with an error.

Usage

fyn add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>

Arguments

PACKAGES

The packages to add, as PEP 508 requirements (e.g., ruff==0.5.0)

Options

--active

Prefer the active virtual environment over the project's virtual environment.

If the project virtual environment is active or no virtual environment is active, this has no effect.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--bounds bounds

The kind of version specifier to use when adding dependencies.

When adding a dependency to the project, if no constraint or URL is provided, a constraint is added based on the latest compatible version of the package. By default, a lower bound constraint is used, e.g., >=1.2.3.

When --frozen is provided, no resolution is performed, and dependencies are always added without constraints.

This option is in preview and may change in any future release.

Possible values:

• lower: Only a lower bound, e.g., >=1.2.3
• major: Allow the same major version, similar to the semver caret, e.g., >=1.2.3, <2.0.0
• minor: Allow the same minor version, similar to the semver tilde, e.g., >=1.2.3, <1.3.0
• exact: Pin the exact version, e.g., ==1.2.3

--branch branch

Branch to use when adding a dependency from Git

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--compile-bytecode, --compile

Compile Python files to bytecode after installation.

By default, fyn does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, fyn will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

May also be set with the UV_COMPILE_BYTECODE environment variable.

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--constraints, --constraint, -c constraints

Constrain versions using the given requirements files.

Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. The constraints will not be added to the project's pyproject.toml file, but will be respected during dependency resolution.

This is equivalent to pip's --constraint option.

May also be set with the UV_CONSTRAINT environment variable.

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--dev

Add the requirements to the development dependency group [env: UV_DEV=]

This option is an alias for --group dev.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--editable

Add the requirements as editable

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra extra

Extras to enable for the dependency.

May be provided more than once.

To add this dependency to an optional extra instead, see --optional.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--frozen

Add dependencies without re-locking the project [env: UV_FROZEN=]

The project environment will not be synced.

--group group

Add the requirements to the specified dependency group.

These requirements will not be included in the published metadata for the project.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--lfs

Whether to use Git LFS when adding a dependency from Git

--link-mode link-mode

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--locked

Assert that the fyn.lock will remain unchanged [env: UV_LOCKED=]

Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, fyn will exit with an error.

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--marker, -m marker

Apply this marker to all added packages

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

May also be set with the UV_NO_BINARY environment variable.

--no-binary-package no-binary-package

Don't install pre-built wheels for a specific package

May also be set with the UV_NO_BINARY_PACKAGE environment variable.

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

May also be set with the UV_NO_BUILD environment variable.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-build-package no-build-package

Don't build source distributions for a specific package

May also be set with the UV_NO_BUILD_PACKAGE environment variable.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-install-local

Do not install local path dependencies

Skips the current project, workspace members, and any other local (path or editable) packages. Only remote/indexed dependencies are installed. Useful in Docker builds to cache heavy third-party dependencies first and layer local packages separately.

The inverse --only-install-local can be used to install only local packages, excluding all remote dependencies.

--no-install-package no-install-package

Do not install the given package(s).

By default, all project's dependencies are installed into the environment. The --no-install-package option allows exclusion of specific packages. Note this can result in a broken environment, and should be used with caution.

The inverse --only-install-package can be used to install only the specified packages, excluding all others.

--no-install-project

Do not install the current project.

By default, the current project is installed into the environment with all of its dependencies. The --no-install-project option allows the project to be excluded, but all of its dependencies are still installed. This is particularly useful in situations like building Docker images where installing the project separately from its dependencies allows optimal layer caching.

The inverse --only-install-project can be used to install only the project itself, excluding all dependencies.

--no-install-workspace

Do not install any workspace members, including the current project.

By default, all workspace members and their dependencies are installed into the environment. The --no-install-workspace option allows exclusion of all the workspace members while retaining their dependencies. This is particularly useful in situations like building Docker images where installing the workspace separately from its dependencies allows optimal layer caching.

The inverse --only-install-workspace can be used to install only workspace members, excluding all other dependencies.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--no-sync

Avoid syncing the virtual environment [env: UV_NO_SYNC=]

--no-workspace

Don't add the dependency as a workspace member.

By default, when adding a dependency that's a local path and is within the workspace directory, fyn will add it as a workspace member; pass --no-workspace to add the package as direct path dependency instead.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--optional optional

Add the requirements to the package's optional dependencies for the specified extra.

The group may then be activated when installing the project with the --extra flag.

To enable an optional extra for this requirement instead, see --extra.

--package package

Add the dependency to a specific package in the workspace

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to use for resolving and syncing.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--raw, --raw-sources

Add a dependency as provided.

By default, fyn will use the tool.fyn.sources section to record source information for Git, local, editable, and direct URL requirements. When --raw is provided, fyn will add source requirements to project.dependencies, rather than tool.fyn.sources.

Additionally, by default, fyn will add bounds to your dependency, e.g., foo>=1.0.0. When --raw is provided, fyn will add the dependency without bounds.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall, --force-reinstall

Reinstall all packages, regardless of whether they're already installed. Implies --refresh

--reinstall-package reinstall-package

Reinstall a specific package, regardless of whether it's already installed. Implies --refresh-package

--requirements, --requirement, -r requirements

Add the packages listed in the given files.

The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--rev rev

Commit to use when adding a dependency from Git

--script script

Add the dependency to the specified Python script, rather than to a project.

If provided, fyn will add the dependency to the script's inline metadata table, in adherence with PEP 723. If no such inline metadata table is present, a new one will be created and added to the script. When executed via fyn run, fyn will create a temporary environment for the script with all inline dependencies installed.

--tag tag

Tag to use when adding a dependency from Git

--upgrade, -U

Allow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh

--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

--workspace

Add the dependency as a workspace member.

By default, fyn will add path dependencies that are within the workspace directory as workspace members. When used with a path dependency, the package will be added to the workspace's members list in the root pyproject.toml file.

fyn remove

Remove dependencies from the project.

Dependencies are removed from the project's pyproject.toml file.

If multiple entries exist for a given dependency, i.e., each with different markers, all of the entries will be removed.

The lockfile and project environment will be updated to reflect the removed dependencies. To skip updating the lockfile, use --frozen. To skip updating the environment, use --no-sync.

If any of the requested dependencies are not present in the project, fyn will exit with an error.

If a package has been manually installed in the environment, i.e., with fyn pip install, it will not be removed by fyn remove.

fyn will search for a project in the current directory or any parent directory. If a project cannot be found, fyn will exit with an error.

Usage

fyn remove [OPTIONS] <PACKAGES>...

Arguments

PACKAGES

The names of the dependencies to remove (e.g., ruff)

Options

--active

Prefer the active virtual environment over the project's virtual environment.

If the project virtual environment is active or no virtual environment is active, this has no effect.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--compile-bytecode, --compile

Compile Python files to bytecode after installation.

By default, fyn does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, fyn will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

May also be set with the UV_COMPILE_BYTECODE environment variable.

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--dev

Remove the packages from the development dependency group [env: UV_DEV=]

This option is an alias for --group dev.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--frozen

Remove dependencies without re-locking the project [env: UV_FROZEN=]

The project environment will not be synced.

--group group

Remove the packages from the specified dependency group

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--locked

Assert that the fyn.lock will remain unchanged [env: UV_LOCKED=]

Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, fyn will exit with an error.

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

May also be set with the UV_NO_BINARY environment variable.

--no-binary-package no-binary-package

Don't install pre-built wheels for a specific package

May also be set with the UV_NO_BINARY_PACKAGE environment variable.

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

May also be set with the UV_NO_BUILD environment variable.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-build-package no-build-package

Don't build source distributions for a specific package

May also be set with the UV_NO_BUILD_PACKAGE environment variable.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--no-sync

Avoid syncing the virtual environment after re-locking the project [env: UV_NO_SYNC=]

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--optional optional

Remove the packages from the project's optional dependencies for the specified extra

--package package

Remove the dependencies from a specific package in the workspace

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to use for resolving and syncing.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall, --force-reinstall

Reinstall all packages, regardless of whether they're already installed. Implies --refresh

--reinstall-package reinstall-package

Reinstall a specific package, regardless of whether it's already installed. Implies --refresh-package

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--script script

Remove the dependency from the specified Python script, rather than from a project.

If provided, fyn will remove the dependency from the script's inline metadata table, in adherence with PEP 723.

--upgrade, -U

Allow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh

--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn version

Read or update the project's version

Usage

fyn version [OPTIONS] [VALUE]

Arguments

VALUE

Set the project version to this value

To update the project using semantic versioning components instead, use --bump.

Options

--active

Prefer the active virtual environment over the project's virtual environment.

If the project virtual environment is active or no virtual environment is active, this has no effect.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--bump bump[=value]

Update the project version using the given semantics

This flag can be passed multiple times.

Possible values:

• major: Increase the major version (e.g., 1.2.3 => 2.0.0)
• minor: Increase the minor version (e.g., 1.2.3 => 1.3.0)
• patch: Increase the patch version (e.g., 1.2.3 => 1.2.4)
• stable: Move from a pre-release to stable version (e.g., 1.2.3b4.post5.dev6 => 1.2.3)
• alpha: Increase the alpha version (e.g., 1.2.3a4 => 1.2.3a5)
• beta: Increase the beta version (e.g., 1.2.3b4 => 1.2.3b5)
• rc: Increase the rc version (e.g., 1.2.3rc4 => 1.2.3rc5)
• post: Increase the post version (e.g., 1.2.3.post5 => 1.2.3.post6)
• dev: Increase the dev version (e.g., 1.2.3a4.dev6 => 1.2.3.dev7)

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--compile-bytecode, --compile

Compile Python files to bytecode after installation.

By default, fyn does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, fyn will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

May also be set with the UV_COMPILE_BYTECODE environment variable.

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--dry-run

Don't write a new version to the pyproject.toml

Instead, the version will be displayed.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--frozen

Update the version without re-locking the project [env: UV_FROZEN=]

The project environment will not be synced.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--locked

Assert that the fyn.lock will remain unchanged [env: UV_LOCKED=]

Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, fyn will exit with an error.

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

May also be set with the UV_NO_BINARY environment variable.

--no-binary-package no-binary-package

Don't install pre-built wheels for a specific package

May also be set with the UV_NO_BINARY_PACKAGE environment variable.

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

May also be set with the UV_NO_BUILD environment variable.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-build-package no-build-package

Don't build source distributions for a specific package

May also be set with the UV_NO_BUILD_PACKAGE environment variable.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--no-sync

Avoid syncing the virtual environment after re-locking the project [env: UV_NO_SYNC=]

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--output-format output-format

The format of the output

[default: text]

Possible values:

• text: Display the version as plain text
• json: Display the version as JSON

--package package

Update the version of a specific package in the workspace

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to use for resolving and syncing.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall, --force-reinstall

Reinstall all packages, regardless of whether they're already installed. Implies --refresh

--reinstall-package reinstall-package

Reinstall a specific package, regardless of whether it's already installed. Implies --refresh-package

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--short

Only show the version

By default, fyn will show the project name before the version.

--upgrade, -U

Allow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh

--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn sync

Update the project's environment.

Syncing ensures that all project dependencies are installed and up-to-date with the lockfile.

By default, an exact sync is performed: fyn removes packages that are not declared as dependencies of the project. Use the --inexact flag to keep extraneous packages. Note that if an extraneous package conflicts with a project dependency, it will still be removed. Additionally, if --no-build-isolation is used, fyn will not remove extraneous packages to avoid removing possible build dependencies.

If the project virtual environment (.venv) does not exist, it will be created.

The project is re-locked before syncing unless the --locked or --frozen flag is provided.

fyn will search for a project in the current directory or any parent directory. If a project cannot be found, fyn will exit with an error.

Note that, when installing from a lockfile, fyn will not provide warnings for yanked package versions.

Usage

fyn sync [OPTIONS]

Options

--active

Sync dependencies to the active virtual environment.

Instead of creating or updating the virtual environment for the project or script, the active virtual environment will be preferred, if the VIRTUAL_ENV environment variable is set.

--all-extras

Include all optional dependencies.

When two or more extras are declared as conflicting in tool.fyn.conflicts, using this flag will always result in an error.

Note that all optional dependencies are always included in the resolution; this option only affects the selection of packages to install.

--all-groups

Include dependencies from all dependency groups.

--no-group can be used to exclude specific groups.

--all-packages

Sync all packages in the workspace.

The workspace's environment (.venv) is updated to include all workspace members.

Any extras or groups specified via --extra, --group, or related options will be applied to all workspace members.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--check

Check if the Python environment is synchronized with the project.

If the environment is not up to date, fyn will exit with an error.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--compile-bytecode, --compile

Compile Python files to bytecode after installation.

By default, fyn does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, fyn will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

May also be set with the UV_COMPILE_BYTECODE environment variable.

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--dry-run

Perform a dry run, without writing the lockfile or modifying the project environment.

In dry-run mode, fyn will resolve the project's dependencies and report on the resulting changes to both the lockfile and the project environment, but will not modify either.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra extra

Include optional dependencies from the specified extra name.

May be provided more than once.

When multiple extras or groups are specified that appear in tool.fyn.conflicts, fyn will report an error.

Note that all optional dependencies are always included in the resolution; this option only affects the selection of packages to install.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--frozen

Sync without updating the fyn.lock file [env: UV_FROZEN=]

Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, fyn will exit with an error. If the pyproject.toml includes changes to dependencies that have not been included in the lockfile yet, they will not be present in the environment.

--group group

Include dependencies from the specified dependency group.

When multiple extras or groups are specified that appear in tool.fyn.conflicts, fyn will report an error.

May be provided multiple times.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--inexact, --no-exact

Do not remove extraneous packages present in the environment.

When enabled, fyn will make the minimum necessary changes to satisfy the requirements. By default, syncing will remove any extraneous packages from the environment

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--locked

Assert that the fyn.lock will remain unchanged [env: UV_LOCKED=]

Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, fyn will exit with an error.

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

May also be set with the UV_NO_BINARY environment variable.

--no-binary-package no-binary-package

Don't install pre-built wheels for a specific package

May also be set with the UV_NO_BINARY_PACKAGE environment variable.

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

May also be set with the UV_NO_BUILD environment variable.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-build-package no-build-package

Don't build source distributions for a specific package

May also be set with the UV_NO_BUILD_PACKAGE environment variable.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-default-groups

Ignore the default dependency groups.

fyn includes the groups defined in tool.fyn.default-groups by default. This disables that option, however, specific groups can still be included with --group.

May also be set with the UV_NO_DEFAULT_GROUPS environment variable.

--no-dev

Disable the development dependency group [env: UV_NO_DEV=]

This option is an alias of --no-group dev. See --no-default-groups to disable all default groups instead.

--no-editable

Install any editable dependencies, including the project and any workspace members, as non-editable [env: UV_NO_EDITABLE=]

--no-extra no-extra

Exclude the specified optional dependencies, if --all-extras is supplied.

May be provided multiple times.

--no-group no-group

Disable the specified dependency group.

This option always takes precedence over default groups, --all-groups, and --group.

May be provided multiple times.

May also be set with the UV_NO_GROUP environment variable.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-install-local

Do not install local path dependencies

Skips the current project, workspace members, and any other local (path or editable) packages. Only remote/indexed dependencies are installed. Useful in Docker builds to cache heavy third-party dependencies first and layer local packages separately.

The inverse --only-install-local can be used to install only local packages, excluding all remote dependencies.

--no-install-package no-install-package

Do not install the given package(s).

By default, all of the project's dependencies are installed into the environment. The --no-install-package option allows exclusion of specific packages. Note this can result in a broken environment, and should be used with caution.

The inverse --only-install-package can be used to install only the specified packages, excluding all others.

--no-install-project

Do not install the current project.

By default, the current project is installed into the environment with all of its dependencies. The --no-install-project option allows the project to be excluded, but all of its dependencies are still installed. This is particularly useful in situations like building Docker images where installing the project separately from its dependencies allows optimal layer caching.

The inverse --only-install-project can be used to install only the project itself, excluding all dependencies.

--no-install-workspace

Do not install any workspace members, including the root project.

By default, all workspace members and their dependencies are installed into the environment. The --no-install-workspace option allows exclusion of all the workspace members while retaining their dependencies. This is particularly useful in situations like building Docker images where installing the workspace separately from its dependencies allows optimal layer caching.

The inverse --only-install-workspace can be used to install only workspace members, excluding all other dependencies.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--only-dev

Only include the development dependency group.

The project and its dependencies will be omitted.

This option is an alias for --only-group dev. Implies --no-default-groups.

--only-group only-group

Only include dependencies from the specified dependency group.

The project and its dependencies will be omitted.

May be provided multiple times. Implies --no-default-groups.

--output-format output-format

Select the output format

[default: text]

Possible values:

• text: Display the result in a human-readable format
• json: Display the result in JSON format

--package package

Sync for specific packages in the workspace.

The workspace's environment (.venv) is updated to reflect the subset of dependencies declared by the specified workspace member packages.

If any workspace member does not exist, fyn will exit with an error.

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to use for the project environment.

By default, the first interpreter that meets the project's requires-python constraint is used.

If a Python interpreter in a virtual environment is provided, the packages will not be synced to the given environment. The interpreter will be used to create a virtual environment in the project.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--python-platform python-platform

The platform for which requirements should be installed.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.

WARNING: When specified, fyn will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.

Possible values:

• windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
• linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
• macos: An alias for aarch64-apple-darwin, the default target for macOS
• x86_64-pc-windows-msvc: A 64-bit x86 Windows target
• aarch64-pc-windows-msvc: An ARM64 Windows target
• i686-pc-windows-msvc: A 32-bit x86 Windows target
• x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
• aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
• x86_64-apple-darwin: An x86 macOS target
• aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
• aarch64-unknown-linux-musl: An ARM64 Linux target
• x86_64-unknown-linux-musl: An x86_64 Linux target
• riscv64-unknown-linux: A RISCV64 Linux target
• x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
• x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
• x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
• x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
• x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
• x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
• x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
• x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
• x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
• x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
• x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
• x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
• x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
• aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
• aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
• aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
• aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
• aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
• aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
• aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
• aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
• aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
• aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
• aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
• aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
• aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
• aarch64-linux-android: An ARM64 Android target
• x86_64-linux-android: An x86_64 Android target
• wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
• arm64-apple-ios: An ARM64 target for iOS device
• arm64-apple-ios-simulator: An ARM64 target for iOS simulator
• x86_64-apple-ios-simulator: An x86_64 target for iOS simulator

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall, --force-reinstall

Reinstall all packages, regardless of whether they're already installed. Implies --refresh

--reinstall-package reinstall-package

Reinstall a specific package, regardless of whether it's already installed. Implies --refresh-package

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--script script

Sync the environment for a Python script, rather than the current project.

If provided, fyn will sync the dependencies based on the script's inline metadata table, in adherence with PEP 723.

--upgrade, -U

Allow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh

--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn lock

Update the project's lockfile.

If the project lockfile (fyn.lock) does not exist, it will be created. If a lockfile is present, its contents will be used as preferences for the resolution.

If there are no changes to the project's dependencies, locking will have no effect unless the --upgrade flag is provided.

Usage

fyn lock [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--check

Check if the lockfile is up-to-date.

Asserts that the fyn.lock would remain unchanged after a resolution. If the lockfile is missing or needs to be updated, fyn will exit with an error.

Equivalent to --locked.

--check-exists, --frozen

Assert that a fyn.lock exists without checking if it is up-to-date [env: UV_FROZEN=]

Equivalent to --frozen.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--dry-run

Perform a dry run, without writing the lockfile.

In dry-run mode, fyn will resolve the project's dependencies and report on the resulting changes, but will not write the lockfile to disk.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

This option is only used when building source distributions.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

May also be set with the UV_NO_BINARY environment variable.

--no-binary-package no-binary-package

Don't install pre-built wheels for a specific package

May also be set with the UV_NO_BINARY_PACKAGE environment variable.

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

May also be set with the UV_NO_BUILD environment variable.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-build-package no-build-package

Don't build source distributions for a specific package

May also be set with the UV_NO_BUILD_PACKAGE environment variable.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to use during resolution.

A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.

The interpreter is also used as the fallback value for the minimum Python version if requires-python is not set.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--script script

Lock the specified Python script, rather than the current project.

If provided, fyn will lock the script (based on its inline metadata table, in adherence with PEP 723) to a .lock file adjacent to the script itself.

--upgrade, -U

Allow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh

--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn upgrade

Upgrade project dependencies.

Re-resolves all (or specified) project dependencies to their latest compatible versions, updates the lockfile, and syncs the environment.

This is equivalent to running fyn lock --upgrade followed by fyn sync.

To upgrade specific packages, pass them as arguments, e.g., fyn upgrade requests flask.

Usage

fyn upgrade [OPTIONS] [PACKAGES]...

Arguments

PACKAGES

The packages to upgrade.

If not provided, all packages in the project will be upgraded to their latest compatible versions.

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--dry-run

Perform a dry run, showing what would be upgraded without making changes

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sync

Do not sync the environment after upgrading the lockfile

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to use during resolution.

May also be set with the UV_PYTHON environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn export

Export the project's lockfile to an alternate format.

At present, requirements.txt, pylock.toml (PEP 751) and CycloneDX v1.5 JSON output formats are supported.

The project is re-locked before exporting unless the --locked or --frozen flag is provided.

fyn will search for a project in the current directory or any parent directory. If a project cannot be found, fyn will exit with an error.

If operating in a workspace, the root will be exported by default; however, specific members can be selected using the --package option.

Usage

fyn export [OPTIONS]

Options

--all-extras

Include all optional dependencies

--all-groups

Include dependencies from all dependency groups.

--no-group can be used to exclude specific groups.

--all-packages

Export the entire workspace.

The dependencies for all workspace members will be included in the exported requirements file.

Any extras or groups specified via --extra, --group, or related options will be applied to all workspace members.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra extra

Include optional dependencies from the specified extra name.

May be provided more than once.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--format format

The format to which fyn.lock should be exported.

Supports requirements.txt, pylock.toml (PEP 751) and CycloneDX v1.5 JSON output formats.

fyn will infer the output format from the file extension of the output file, if provided. Otherwise, defaults to requirements.txt.

Possible values:

• requirements.txt: Export in requirements.txt format
• pylock.toml: Export in pylock.toml format
• cyclonedx1.5: Export in CycloneDX v1.5 JSON format

--frozen

Do not update the fyn.lock before exporting [env: UV_FROZEN=]

If a fyn.lock does not exist, fyn will exit with an error.

--group group

Include dependencies from the specified dependency group.

May be provided multiple times.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

This option is only used when building source distributions.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--locked

Assert that the fyn.lock will remain unchanged [env: UV_LOCKED=]

Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, fyn will exit with an error.

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-annotate

Exclude comment annotations indicating the source of each package

--no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

May also be set with the UV_NO_BINARY environment variable.

--no-binary-package no-binary-package

Don't install pre-built wheels for a specific package

May also be set with the UV_NO_BINARY_PACKAGE environment variable.

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

May also be set with the UV_NO_BUILD environment variable.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-build-package no-build-package

Don't build source distributions for a specific package

May also be set with the UV_NO_BUILD_PACKAGE environment variable.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-default-groups

Ignore the default dependency groups.

fyn includes the groups defined in tool.fyn.default-groups by default. This disables that option, however, specific groups can still be included with --group.

May also be set with the UV_NO_DEFAULT_GROUPS environment variable.

--no-dev

Disable the development dependency group [env: UV_NO_DEV=]

This option is an alias of --no-group dev. See --no-default-groups to disable all default groups instead.

--no-editable

Export any editable dependencies, including the project and any workspace members, as non-editable [env: UV_NO_EDITABLE=]

--no-emit-local, --no-install-local

Do not include local path dependencies in the exported requirements.

Omits the current project, workspace members, and any other local (path or editable) packages from the export. Only remote/indexed dependencies are written. Useful for Docker and CI flows that want to export and cache third-party dependencies first.

The inverse --only-emit-local can be used to emit only local packages, excluding all remote dependencies.

--no-emit-package, --no-install-package no-emit-package

Do not emit the given package(s).

By default, all project's dependencies are included in the exported requirements file. The --no-emit-package option allows exclusion of specific packages.

The inverse --only-emit-package can be used to emit only the specified packages, excluding all others.

--no-emit-project, --no-install-project

Do not emit the current project.

By default, the current project is included in the exported requirements file with all of its dependencies. The --no-emit-project option allows the project to be excluded, but all of its dependencies to remain included.

The inverse --only-emit-project can be used to emit only the project itself, excluding all dependencies.

--no-emit-workspace, --no-install-workspace

Do not emit any workspace members, including the root project.

By default, all workspace members and their dependencies are included in the exported requirements file, with all of their dependencies. The --no-emit-workspace option allows exclusion of all the workspace members while retaining their dependencies.

The inverse --only-emit-workspace can be used to emit only workspace members, excluding all other dependencies.

--no-extra no-extra

Exclude the specified optional dependencies, if --all-extras is supplied.

May be provided multiple times.

--no-group no-group

Disable the specified dependency group.

This option always takes precedence over default groups, --all-groups, and --group.

May be provided multiple times.

May also be set with the UV_NO_GROUP environment variable.

--no-hashes

Omit hashes in the generated output

--no-header

Exclude the comment header at the top of the generated output file

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--only-dev

Only include the development dependency group.

The project and its dependencies will be omitted.

This option is an alias for --only-group dev. Implies --no-default-groups.

--only-group only-group

Only include dependencies from the specified dependency group.

The project and its dependencies will be omitted.

May be provided multiple times. Implies --no-default-groups.

--output-file, -o output-file

Write the exported requirements to the given file

--package package

Export the dependencies for specific packages in the workspace.

If any workspace member does not exist, fyn will exit with an error.

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--prune package

Prune the given package from the dependency tree.

Pruned packages will be excluded from the exported requirements file, as will any dependencies that are no longer required after the pruned package is removed.

--python, -p python

The Python interpreter to use during resolution.

A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.

The interpreter is also used as the fallback value for the minimum Python version if requires-python is not set.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--script script

Export the dependencies for the specified PEP 723 Python script, rather than the current project.

If provided, fyn will resolve the dependencies based on its inline metadata table, in adherence with PEP 723.

--upgrade, -U

Allow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh

--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn tree

Display the project's dependency tree

Usage

fyn tree [OPTIONS]

Options

--all-groups

Include dependencies from all dependency groups.

--no-group can be used to exclude specific groups.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--depth, -d depth

Maximum display depth of the dependency tree

[default: 255]

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--frozen

Display the requirements without locking the project [env: UV_FROZEN=]

If the lockfile is missing, fyn will exit with an error.

--group group

Include dependencies from the specified dependency group.

May be provided multiple times.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--invert, --reverse

Show the reverse dependencies for the given package. This flag will invert the tree and display the packages that depend on the given package

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

This option is only used when building source distributions.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--locked

Assert that the fyn.lock will remain unchanged [env: UV_LOCKED=]

Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, fyn will exit with an error.

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

May also be set with the UV_NO_BINARY environment variable.

--no-binary-package no-binary-package

Don't install pre-built wheels for a specific package

May also be set with the UV_NO_BINARY_PACKAGE environment variable.

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

May also be set with the UV_NO_BUILD environment variable.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-build-package no-build-package

Don't build source distributions for a specific package

May also be set with the UV_NO_BUILD_PACKAGE environment variable.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-dedupe

Do not de-duplicate repeated dependencies. Usually, when a package has already displayed its dependencies, further occurrences will not re-display its dependencies, and will include a (*) to indicate it has already been shown. This flag will cause those duplicates to be repeated

--no-default-groups

Ignore the default dependency groups.

fyn includes the groups defined in tool.fyn.default-groups by default. This disables that option, however, specific groups can still be included with --group.

May also be set with the UV_NO_DEFAULT_GROUPS environment variable.

--no-dev

Disable the development dependency group [env: UV_NO_DEV=]

This option is an alias of --no-group dev. See --no-default-groups to disable all default groups instead.

--no-group no-group

Disable the specified dependency group.

This option always takes precedence over default groups, --all-groups, and --group.

May be provided multiple times.

May also be set with the UV_NO_GROUP environment variable.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--only-dev

Only include the development dependency group.

The project and its dependencies will be omitted.

This option is an alias for --only-group dev. Implies --no-default-groups.

--only-group only-group

Only include dependencies from the specified dependency group.

The project and its dependencies will be omitted.

May be provided multiple times. Implies --no-default-groups.

--outdated

Show the latest available version of each package in the tree

--package package

Display only the specified packages

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--prune prune

Prune the given package from the display of the dependency tree

--python, -p python

The Python interpreter to use for locking and filtering.

By default, the tree is filtered to match the platform as reported by the Python interpreter. Use --universal to display the tree for all platforms, or use --python-version or --python-platform to override a subset of markers.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--python-platform python-platform

The platform to use when filtering the tree.

For example, pass --platform windows to display the dependencies that would be included when installing on Windows.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

Possible values:

• windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
• linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
• macos: An alias for aarch64-apple-darwin, the default target for macOS
• x86_64-pc-windows-msvc: A 64-bit x86 Windows target
• aarch64-pc-windows-msvc: An ARM64 Windows target
• i686-pc-windows-msvc: A 32-bit x86 Windows target
• x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
• aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
• x86_64-apple-darwin: An x86 macOS target
• aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
• aarch64-unknown-linux-musl: An ARM64 Linux target
• x86_64-unknown-linux-musl: An x86_64 Linux target
• riscv64-unknown-linux: A RISCV64 Linux target
• x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
• x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
• x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
• x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
• x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
• x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
• x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
• x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
• x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
• x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
• x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
• x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
• x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
• aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
• aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
• aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
• aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
• aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
• aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
• aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
• aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
• aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
• aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
• aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
• aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
• aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
• aarch64-linux-android: An ARM64 Android target
• x86_64-linux-android: An x86_64 Android target
• wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
• arm64-apple-ios: An ARM64 target for iOS device
• arm64-apple-ios-simulator: An ARM64 target for iOS simulator
• x86_64-apple-ios-simulator: An x86_64 target for iOS simulator

--python-version python-version

The Python version to use when filtering the tree.

For example, pass --python-version 3.10 to display the dependencies that would be included when installing on Python 3.10.

Defaults to the version of the discovered Python interpreter.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--script script

Show the dependency tree the specified PEP 723 Python script, rather than the current project.

If provided, fyn will resolve the dependencies based on its inline metadata table, in adherence with PEP 723.

--show-sizes

Show compressed wheel sizes for packages in the tree

--universal

Show a platform-independent dependency tree.

Shows resolved package versions for all Python versions and platforms, rather than filtering to those that are relevant for the current environment.

Multiple versions may be shown for a each package.

--upgrade, -U

Allow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh

--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn format

Format Python code in the project.

Formats Python code using the Ruff formatter. By default, all Python files in the project are formatted. This command has the same behavior as running ruff format in the project root.

To check if files are formatted without modifying them, use --check. To see a diff of formatting changes, use --diff.

Additional arguments can be passed to Ruff after --.

Usage

fyn format [OPTIONS] [-- <EXTRA_ARGS>...]

Arguments

EXTRA_ARGS

Additional arguments to pass to Ruff.

For example, use fyn format -- --line-length 100 to set the line length or fyn format -- src/module/foo.py to format a specific file.

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--check

Check if files are formatted without applying changes

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--diff

Show a diff of formatting changes without applying them.

Implies --check.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--exclude-newer exclude-newer

Limit candidate Ruff versions to those released prior to the given date.

Accepts a superset of RFC 3339 (e.g., 2006-12-02T02:07:43Z) or local date in the same format (e.g. 2006-12-02), as well as durations relative to "now" (e.g., -1 week).

May also be set with the UV_EXCLUDE_NEWER environment variable.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-project

Avoid discovering a project or workspace.

Instead of running the formatter in the context of the current project, run it in the context of the current directory. This is useful when the current directory is not a project.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

--version version

The version of Ruff to use for formatting.

Accepts either a version (e.g., 0.8.2) which will be treated as an exact pin, a version specifier (e.g., >=0.8.0), or latest to use the latest available version.

By default, a constrained version range of Ruff will be used (e.g., >=0.15,<0.16).

fyn audit

Audit the project's dependencies.

Dependencies are audited for known vulnerabilities, as well as 'adverse' statuses such as deprecation and quarantine.

Usage

fyn audit [OPTIONS]

Options

--all-extras

Include all optional dependencies.

Optional dependencies are defined via project.optional-dependencies in a pyproject.toml.

This option is only available when running in a project.

--all-groups

Include dependencies from all dependency groups.

--no-group can be used to exclude specific groups.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra extra

Include optional dependencies from the specified extra name.

May be provided more than once.

This option is only available when running in a project.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--frozen

Audit the requirements without locking the project [env: UV_FROZEN=]

If the lockfile is missing, fyn will exit with an error.

--group group

Include dependencies from the specified dependency group.

May be provided multiple times.

--help, -h

Display the concise help for this command

--ignore ignore

A vulnerability ID to ignore during auditing.

May be provided multiple times.

--ignore-until-fixed ignore-until-fixed

A vulnerability ID to ignore during auditing, but only while no fix is available.

May be provided multiple times.

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

This option is only used when building source distributions.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--locked

Assert that the fyn.lock will remain unchanged [env: UV_LOCKED=]

Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, fyn will exit with an error.

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

May also be set with the UV_NO_BINARY environment variable.

--no-binary-package no-binary-package

Don't install pre-built wheels for a specific package

May also be set with the UV_NO_BINARY_PACKAGE environment variable.

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

May also be set with the UV_NO_BUILD environment variable.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-build-package no-build-package

Don't build source distributions for a specific package

May also be set with the UV_NO_BUILD_PACKAGE environment variable.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-default-groups

Ignore the default dependency groups.

fyn includes the groups defined in tool.fyn.default-groups by default. This disables that option, however, specific groups can still be included with --group.

May also be set with the UV_NO_DEFAULT_GROUPS environment variable.

--no-dev

Disable the development dependency group [env: UV_NO_DEV=]

This option is an alias of --no-group dev. See --no-default-groups to disable all default groups instead.

This option is only available when running in a project.

--no-extra no-extra

Exclude the specified optional dependencies, if --all-extras is supplied.

May be provided multiple times.

--no-group no-group

Disable the specified dependency group.

This option always takes precedence over default groups, --all-groups, and --group.

May be provided multiple times.

May also be set with the UV_NO_GROUP environment variable.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--only-dev

Only include the development dependency group.

The project and its dependencies will be omitted.

This option is an alias for --only-group dev. Implies --no-default-groups.

--only-group only-group

Only include dependencies from the specified dependency group.

The project and its dependencies will be omitted.

May be provided multiple times. Implies --no-default-groups.

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python-platform python-platform

The platform to use when auditing.

For example, pass --platform windows to audit the dependencies that would be included when installing on Windows.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

Possible values:

• windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
• linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
• macos: An alias for aarch64-apple-darwin, the default target for macOS
• x86_64-pc-windows-msvc: A 64-bit x86 Windows target
• aarch64-pc-windows-msvc: An ARM64 Windows target
• i686-pc-windows-msvc: A 32-bit x86 Windows target
• x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
• aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
• x86_64-apple-darwin: An x86 macOS target
• aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
• aarch64-unknown-linux-musl: An ARM64 Linux target
• x86_64-unknown-linux-musl: An x86_64 Linux target
• riscv64-unknown-linux: A RISCV64 Linux target
• x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
• x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
• x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
• x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
• x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
• x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
• x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
• x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
• x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
• x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
• x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
• x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
• x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
• aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
• aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
• aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
• aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
• aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
• aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
• aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
• aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
• aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
• aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
• aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
• aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
• aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
• aarch64-linux-android: An ARM64 Android target
• x86_64-linux-android: An x86_64 Android target
• wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
• arm64-apple-ios: An ARM64 target for iOS device
• arm64-apple-ios-simulator: An ARM64 target for iOS simulator
• x86_64-apple-ios-simulator: An x86_64 target for iOS simulator

--python-version python-version

The Python version to use when auditing.

For example, pass --python-version 3.10 to audit the dependencies that would be included when installing on Python 3.10.

Defaults to the version of the discovered Python interpreter.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--script script

Audit the specified PEP 723 Python script, rather than the current project.

The specified script must be locked, i.e. with fyn lock --script <script> before it can be audited.

--service-format service-format

The service format to use for vulnerability lookups.

Each service format has a default URL, which can be changed with --service-url. The defaults are:

• OSV: https://api.osv.dev/

[default: osv]

Possible values:

• osv

--service-url service-url

The base URL for the vulnerability service API.

If not provided, the default URL for the selected service will be used.

The service needs to use the OSV protocol, unless a different format was requested by --service-format.

--upgrade, -U

Allow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh

--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn tool

Run and install commands provided by Python packages

Usage

fyn tool [OPTIONS] <COMMAND>

Commands

fyn tool run

Run a command provided by a Python package

fyn tool install

Install commands provided by a Python package

fyn tool upgrade

Upgrade installed tools

fyn tool list

List installed tools

fyn tool uninstall

Uninstall a tool

fyn tool update-shell

Ensure that the tool executable directory is on the PATH

fyn tool dir

Show the path to the fyn tools directory

fyn tool run

Run a command provided by a Python package.

By default, the package to install is assumed to match the command name.

The name of the command can include an exact version in the format <package>@<version>, e.g., fyn tool run ruff@0.3.0. If more complex version specification is desired or if the command is provided by a different package, use --from.

fynx can be used to invoke Python, e.g., with fynx python or fynx python@<version>. A Python interpreter will be started in an isolated virtual environment.

If the tool was previously installed, i.e., via fyn tool install, the installed version will be used unless a version is requested or the --isolated flag is used.

fynx is provided as a convenient alias for fyn tool run, their behavior is identical.

If no command is provided, the installed tools are displayed.

Packages are installed into an ephemeral virtual environment in the fyn cache directory.

Usage

fyn tool run [OPTIONS] [COMMAND]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--build-constraints, --build-constraint, -b build-constraints

Constrain build dependencies using the given requirements files when building source distributions.

Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.

May also be set with the UV_BUILD_CONSTRAINT environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--compile-bytecode, --compile

Compile Python files to bytecode after installation.

By default, fyn does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, fyn will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

May also be set with the UV_COMPILE_BYTECODE environment variable.

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--constraints, --constraint, -c constraints

Constrain versions using the given requirements files.

Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.

This is equivalent to pip's --constraint option.

May also be set with the UV_CONSTRAINT environment variable.

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--env-file env-file

Load environment variables from a .env file.

Can be provided multiple times, with subsequent files overriding values defined in previous files.

May also be set with the UV_ENV_FILE environment variable.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--from from

Use the given package to provide the command.

By default, the package name is assumed to match the command name.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--isolated

Run the tool in an isolated virtual environment, ignoring any already-installed tools [env: UV_ISOLATED=]

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--lfs

Whether to use Git LFS when adding a dependency from Git

--link-mode link-mode

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

May also be set with the UV_NO_BINARY environment variable.

--no-binary-package no-binary-package

Don't install pre-built wheels for a specific package

May also be set with the UV_NO_BINARY_PACKAGE environment variable.

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

May also be set with the UV_NO_BUILD environment variable.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-build-package no-build-package

Don't build source distributions for a specific package

May also be set with the UV_NO_BUILD_PACKAGE environment variable.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-env-file

Avoid reading environment variables from a .env file [env: UV_NO_ENV_FILE=]

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--overrides, --override overrides

Override versions using the given requirements files.

Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.

While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.

May also be set with the UV_OVERRIDE environment variable.

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to use to build the run environment.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--python-platform python-platform

The platform for which requirements should be installed.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.

WARNING: When specified, fyn will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.

Possible values:

• windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
• linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
• macos: An alias for aarch64-apple-darwin, the default target for macOS
• x86_64-pc-windows-msvc: A 64-bit x86 Windows target
• aarch64-pc-windows-msvc: An ARM64 Windows target
• i686-pc-windows-msvc: A 32-bit x86 Windows target
• x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
• aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
• x86_64-apple-darwin: An x86 macOS target
• aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
• aarch64-unknown-linux-musl: An ARM64 Linux target
• x86_64-unknown-linux-musl: An x86_64 Linux target
• riscv64-unknown-linux: A RISCV64 Linux target
• x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
• x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
• x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
• x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
• x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
• x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
• x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
• x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
• x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
• x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
• x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
• x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
• x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
• aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
• aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
• aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
• aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
• aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
• aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
• aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
• aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
• aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
• aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
• aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
• aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
• aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
• aarch64-linux-android: An ARM64 Android target
• x86_64-linux-android: An x86_64 Android target
• wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
• arm64-apple-ios: An ARM64 target for iOS device
• arm64-apple-ios-simulator: An ARM64 target for iOS simulator
• x86_64-apple-ios-simulator: An x86_64 target for iOS simulator

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall, --force-reinstall

Reinstall all packages, regardless of whether they're already installed. Implies --refresh

--reinstall-package reinstall-package

Reinstall a specific package, regardless of whether it's already installed. Implies --refresh-package

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--torch-backend torch-backend

The backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto)

When set, fyn will ignore the configured index URLs for packages in the PyTorch ecosystem, and will instead use the defined backend.

For example, when set to cpu, fyn will use the CPU-only PyTorch index; when set to cu126, fyn will use the PyTorch index for CUDA 12.6.

The auto mode will attempt to detect the appropriate PyTorch index based on the currently installed CUDA drivers.

This option is in preview and may change in any future release.

May also be set with the UV_TORCH_BACKEND environment variable.

Possible values:

• auto: Select the appropriate PyTorch index based on the operating system and CUDA driver version
• cpu: Use the CPU-only PyTorch index
• cu130: Use the PyTorch index for CUDA 13.0
• cu129: Use the PyTorch index for CUDA 12.9
• cu128: Use the PyTorch index for CUDA 12.8
• cu126: Use the PyTorch index for CUDA 12.6
• cu125: Use the PyTorch index for CUDA 12.5
• cu124: Use the PyTorch index for CUDA 12.4
• cu123: Use the PyTorch index for CUDA 12.3
• cu122: Use the PyTorch index for CUDA 12.2
• cu121: Use the PyTorch index for CUDA 12.1
• cu120: Use the PyTorch index for CUDA 12.0
• cu118: Use the PyTorch index for CUDA 11.8
• cu117: Use the PyTorch index for CUDA 11.7
• cu116: Use the PyTorch index for CUDA 11.6
• cu115: Use the PyTorch index for CUDA 11.5
• cu114: Use the PyTorch index for CUDA 11.4
• cu113: Use the PyTorch index for CUDA 11.3
• cu112: Use the PyTorch index for CUDA 11.2
• cu111: Use the PyTorch index for CUDA 11.1
• cu110: Use the PyTorch index for CUDA 11.0
• cu102: Use the PyTorch index for CUDA 10.2
• cu101: Use the PyTorch index for CUDA 10.1
• cu100: Use the PyTorch index for CUDA 10.0
• cu92: Use the PyTorch index for CUDA 9.2
• cu91: Use the PyTorch index for CUDA 9.1
• cu90: Use the PyTorch index for CUDA 9.0
• cu80: Use the PyTorch index for CUDA 8.0
• rocm7.1: Use the PyTorch index for ROCm 7.1
• rocm7.0: Use the PyTorch index for ROCm 7.0
• rocm6.4: Use the PyTorch index for ROCm 6.4
• rocm6.3: Use the PyTorch index for ROCm 6.3
• rocm6.2.4: Use the PyTorch index for ROCm 6.2.4
• rocm6.2: Use the PyTorch index for ROCm 6.2
• rocm6.1: Use the PyTorch index for ROCm 6.1
• rocm6.0: Use the PyTorch index for ROCm 6.0
• rocm5.7: Use the PyTorch index for ROCm 5.7
• rocm5.6: Use the PyTorch index for ROCm 5.6
• rocm5.5: Use the PyTorch index for ROCm 5.5
• rocm5.4.2: Use the PyTorch index for ROCm 5.4.2
• rocm5.4: Use the PyTorch index for ROCm 5.4
• rocm5.3: Use the PyTorch index for ROCm 5.3
• rocm5.2: Use the PyTorch index for ROCm 5.2
• rocm5.1.1: Use the PyTorch index for ROCm 5.1.1
• rocm4.2: Use the PyTorch index for ROCm 4.2
• rocm4.1: Use the PyTorch index for ROCm 4.1
• rocm4.0.1: Use the PyTorch index for ROCm 4.0.1
• xpu: Use the PyTorch index for Intel XPU

--upgrade, -U

Allow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh

--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

--with, -w with

Run with the given packages installed

--with-editable with-editable

Run with the given packages installed in editable mode

When used in a project, these dependencies will be layered on top of the fyn tool's environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified.

--with-requirements with-requirements

Run with the packages listed in the given files.

The following formats are supported: requirements.txt, .py files with inline metadata, and pylock.toml.

fyn tool install

Install commands provided by a Python package.

Packages are installed into an isolated virtual environment in the fyn tools directory. The executables are linked the tool executable directory, which is determined according to the XDG standard and can be retrieved with fyn tool dir --bin.

If the tool was previously installed, the existing tool will generally be replaced.

Usage

fyn tool install [OPTIONS] <PACKAGE>

Arguments

PACKAGE

The package to install commands from

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--build-constraints, --build-constraint, -b build-constraints

Constrain build dependencies using the given requirements files when building source distributions.

Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.

May also be set with the UV_BUILD_CONSTRAINT environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--compile-bytecode, --compile

Compile Python files to bytecode after installation.

By default, fyn does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, fyn will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

May also be set with the UV_COMPILE_BYTECODE environment variable.

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--constraints, --constraint, -c constraints

Constrain versions using the given requirements files.

Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.

This is equivalent to pip's --constraint option.

May also be set with the UV_CONSTRAINT environment variable.

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--editable, -e

Install the target package in editable mode, such that changes in the package's source directory are reflected without reinstallation

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--excludes, --exclude excludes

Exclude packages from resolution using the given requirements files.

Excludes files are requirements.txt-like files that specify packages to exclude from the resolution. When a package is excluded, it will be omitted from the dependency list entirely and its own dependencies will be ignored during the resolution phase. Excludes are unconditional in that requirement specifiers and markers are ignored; any package listed in the provided file will be omitted from all resolved environments.

May also be set with the UV_EXCLUDE environment variable.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--force

Force installation of the tool.

Will recreate any existing environment for the tool and replace any existing entry points with the same name in the executable directory.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--lfs

Whether to use Git LFS when adding a dependency from Git

--link-mode link-mode

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

May also be set with the UV_NO_BINARY environment variable.

--no-binary-package no-binary-package

Don't install pre-built wheels for a specific package

May also be set with the UV_NO_BINARY_PACKAGE environment variable.

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

May also be set with the UV_NO_BUILD environment variable.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-build-package no-build-package

Don't build source distributions for a specific package

May also be set with the UV_NO_BUILD_PACKAGE environment variable.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--overrides, --override overrides

Override versions using the given requirements files.

Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.

While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.

May also be set with the UV_OVERRIDE environment variable.

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to use to build the tool environment.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--python-platform python-platform

The platform for which requirements should be installed.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.

WARNING: When specified, fyn will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.

Possible values:

• windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
• linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
• macos: An alias for aarch64-apple-darwin, the default target for macOS
• x86_64-pc-windows-msvc: A 64-bit x86 Windows target
• aarch64-pc-windows-msvc: An ARM64 Windows target
• i686-pc-windows-msvc: A 32-bit x86 Windows target
• x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
• aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
• x86_64-apple-darwin: An x86 macOS target
• aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
• aarch64-unknown-linux-musl: An ARM64 Linux target
• x86_64-unknown-linux-musl: An x86_64 Linux target
• riscv64-unknown-linux: A RISCV64 Linux target
• x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
• x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
• x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
• x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
• x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
• x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
• x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
• x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
• x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
• x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
• x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
• x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
• x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
• aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
• aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
• aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
• aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
• aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
• aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
• aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
• aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
• aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
• aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
• aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
• aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
• aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
• aarch64-linux-android: An ARM64 Android target
• x86_64-linux-android: An x86_64 Android target
• wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
• arm64-apple-ios: An ARM64 target for iOS device
• arm64-apple-ios-simulator: An ARM64 target for iOS simulator
• x86_64-apple-ios-simulator: An x86_64 target for iOS simulator

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall, --force-reinstall

Reinstall all packages, regardless of whether they're already installed. Implies --refresh

--reinstall-package reinstall-package

Reinstall a specific package, regardless of whether it's already installed. Implies --refresh-package

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--torch-backend torch-backend

The backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto)

When set, fyn will ignore the configured index URLs for packages in the PyTorch ecosystem, and will instead use the defined backend.

For example, when set to cpu, fyn will use the CPU-only PyTorch index; when set to cu126, fyn will use the PyTorch index for CUDA 12.6.

The auto mode will attempt to detect the appropriate PyTorch index based on the currently installed CUDA drivers.

This option is in preview and may change in any future release.

May also be set with the UV_TORCH_BACKEND environment variable.

Possible values:

• auto: Select the appropriate PyTorch index based on the operating system and CUDA driver version
• cpu: Use the CPU-only PyTorch index
• cu130: Use the PyTorch index for CUDA 13.0
• cu129: Use the PyTorch index for CUDA 12.9
• cu128: Use the PyTorch index for CUDA 12.8
• cu126: Use the PyTorch index for CUDA 12.6
• cu125: Use the PyTorch index for CUDA 12.5
• cu124: Use the PyTorch index for CUDA 12.4
• cu123: Use the PyTorch index for CUDA 12.3
• cu122: Use the PyTorch index for CUDA 12.2
• cu121: Use the PyTorch index for CUDA 12.1
• cu120: Use the PyTorch index for CUDA 12.0
• cu118: Use the PyTorch index for CUDA 11.8
• cu117: Use the PyTorch index for CUDA 11.7
• cu116: Use the PyTorch index for CUDA 11.6
• cu115: Use the PyTorch index for CUDA 11.5
• cu114: Use the PyTorch index for CUDA 11.4
• cu113: Use the PyTorch index for CUDA 11.3
• cu112: Use the PyTorch index for CUDA 11.2
• cu111: Use the PyTorch index for CUDA 11.1
• cu110: Use the PyTorch index for CUDA 11.0
• cu102: Use the PyTorch index for CUDA 10.2
• cu101: Use the PyTorch index for CUDA 10.1
• cu100: Use the PyTorch index for CUDA 10.0
• cu92: Use the PyTorch index for CUDA 9.2
• cu91: Use the PyTorch index for CUDA 9.1
• cu90: Use the PyTorch index for CUDA 9.0
• cu80: Use the PyTorch index for CUDA 8.0
• rocm7.1: Use the PyTorch index for ROCm 7.1
• rocm7.0: Use the PyTorch index for ROCm 7.0
• rocm6.4: Use the PyTorch index for ROCm 6.4
• rocm6.3: Use the PyTorch index for ROCm 6.3
• rocm6.2.4: Use the PyTorch index for ROCm 6.2.4
• rocm6.2: Use the PyTorch index for ROCm 6.2
• rocm6.1: Use the PyTorch index for ROCm 6.1
• rocm6.0: Use the PyTorch index for ROCm 6.0
• rocm5.7: Use the PyTorch index for ROCm 5.7
• rocm5.6: Use the PyTorch index for ROCm 5.6
• rocm5.5: Use the PyTorch index for ROCm 5.5
• rocm5.4.2: Use the PyTorch index for ROCm 5.4.2
• rocm5.4: Use the PyTorch index for ROCm 5.4
• rocm5.3: Use the PyTorch index for ROCm 5.3
• rocm5.2: Use the PyTorch index for ROCm 5.2
• rocm5.1.1: Use the PyTorch index for ROCm 5.1.1
• rocm4.2: Use the PyTorch index for ROCm 4.2
• rocm4.1: Use the PyTorch index for ROCm 4.1
• rocm4.0.1: Use the PyTorch index for ROCm 4.0.1
• xpu: Use the PyTorch index for Intel XPU

--upgrade, -U

Allow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh

--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

--with, -w with

Include the following additional requirements

--with-editable with-editable

Include the given packages in editable mode

--with-executables-from with-executables-from

Install executables from the following packages

--with-requirements with-requirements

Run with the packages listed in the given files.

The following formats are supported: requirements.txt, .py files with inline metadata, and pylock.toml.

fyn tool upgrade

Upgrade installed tools.

If a tool was installed with version constraints, they will be respected on upgrade — to upgrade a tool beyond the originally provided constraints, use fyn tool install again.

If a tool was installed with specific settings, they will be respected on upgraded. For example, if --prereleases allow was provided during installation, it will continue to be respected in upgrades.

Usage

fyn tool upgrade [OPTIONS] <NAME>...

Arguments

NAME

The name of the tool to upgrade, along with an optional version specifier

Options

--all

Upgrade all tools

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--compile-bytecode, --compile

Compile Python files to bytecode after installation.

By default, fyn does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, fyn will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

May also be set with the UV_COMPILE_BYTECODE environment variable.

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-setting-package, --config-settings-package config-setting-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

May also be set with the UV_NO_BINARY environment variable.

--no-binary-package no-binary-package

Don't install pre-built wheels for a specific package

May also be set with the UV_NO_BINARY_PACKAGE environment variable.

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

May also be set with the UV_NO_BUILD environment variable.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-build-package no-build-package

Don't build source distributions for a specific package

May also be set with the UV_NO_BUILD_PACKAGE environment variable.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

Upgrade a tool, and specify it to use the given Python interpreter to build its environment. Use with --all to apply to all tools.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--python-platform python-platform

The platform for which requirements should be installed.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.

WARNING: When specified, fyn will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.

Possible values:

• windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
• linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
• macos: An alias for aarch64-apple-darwin, the default target for macOS
• x86_64-pc-windows-msvc: A 64-bit x86 Windows target
• aarch64-pc-windows-msvc: An ARM64 Windows target
• i686-pc-windows-msvc: A 32-bit x86 Windows target
• x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
• aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
• x86_64-apple-darwin: An x86 macOS target
• aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
• aarch64-unknown-linux-musl: An ARM64 Linux target
• x86_64-unknown-linux-musl: An x86_64 Linux target
• riscv64-unknown-linux: A RISCV64 Linux target
• x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
• x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
• x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
• x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
• x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
• x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
• x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
• x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
• x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
• x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
• x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
• x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
• x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
• aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
• aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
• aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
• aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
• aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
• aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
• aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
• aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
• aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
• aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
• aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
• aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
• aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
• aarch64-linux-android: An ARM64 Android target
• x86_64-linux-android: An x86_64 Android target
• wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
• arm64-apple-ios: An ARM64 target for iOS device
• arm64-apple-ios-simulator: An ARM64 target for iOS simulator
• x86_64-apple-ios-simulator: An x86_64 target for iOS simulator

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--reinstall, --force-reinstall

Reinstall all packages, regardless of whether they're already installed. Implies --refresh

--reinstall-package reinstall-package

Reinstall a specific package, regardless of whether it's already installed. Implies --refresh-package

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn tool list

List installed tools

Usage

fyn tool list [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--outdated

List outdated tools.

The latest version of each tool will be shown alongside the installed version. Up-to-date tools will be omitted from the output.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--show-extras

Whether to display the extra requirements installed with each tool

--show-paths

Whether to display the path to each tool environment and installed executable

--show-python

Whether to display the Python version associated with each tool

--show-version-specifiers

Whether to display the version specifier(s) used to install each tool

--show-with

Whether to display the additional requirements installed with each tool

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn tool uninstall

Uninstall a tool

Usage

fyn tool uninstall [OPTIONS] <NAME>...

Arguments

NAME

The name of the tool to uninstall

Options

--all

Uninstall all tools

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn tool update-shell

Ensure that the tool executable directory is on the PATH.

If the tool executable directory is not present on the PATH, fyn will attempt to add it to the relevant shell configuration files.

If the shell configuration files already include a blurb to add the executable directory to the path, but the directory is not present on the PATH, fyn will exit with an error.

The tool executable directory is determined according to the XDG standard and can be retrieved with fyn tool dir --bin.

Usage

fyn tool update-shell [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn tool dir

Show the path to the fyn tools directory.

The tools directory is used to store environments and metadata for installed tools.

By default, tools are stored in the fyn data directory at $XDG_DATA_HOME/fyn/tools or $HOME/.local/share/fyn/tools on Unix and %APPDATA%\fyn\data\tools on Windows.

The tool installation directory may be overridden with $UV_TOOL_DIR.

To instead view the directory fyn installs executables into, use the --bin flag.

Usage

fyn tool dir [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--bin

Show the directory into which fyn tool will install executables.

By default, fyn tool dir shows the directory into which the tool Python environments themselves are installed, rather than the directory containing the linked executables.

The tool executable directory is determined according to the XDG standard and is derived from the following environment variables, in order of preference:

• $UV_TOOL_BIN_DIR
• $XDG_BIN_HOME
• $XDG_DATA_HOME/../bin
• $HOME/.local/bin

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn python

Manage Python versions and installations

Generally, fyn first searches for Python in a virtual environment, either active or in a .venv directory in the current working directory or any parent directory. If a virtual environment is not required, fyn will then search for a Python interpreter. Python interpreters are found by searching for Python executables in the PATH environment variable.

On Windows, the registry is also searched for Python executables.

By default, fyn will download Python if a version cannot be found. This behavior can be disabled with the --no-python-downloads flag or the python-downloads setting.

The --python option allows requesting a different interpreter.

The following Python version request formats are supported:

• <version> e.g. 3, 3.12, 3.12.3
• <version-specifier> e.g. >=3.12,<3.13
• <version><short-variant> (e.g., 3.13t, 3.12.0d)
• <version>+<variant> (e.g., 3.13+freethreaded, 3.12.0+debug)
• <implementation> e.g. cpython or cp
• <implementation>@<version> e.g. cpython@3.12
• <implementation><version> e.g. cpython3.12 or cp312
• <implementation><version-specifier> e.g. cpython>=3.12,<3.13
• <implementation>-<version>-<os>-<arch>-<libc> e.g. cpython-3.12.3-macos-aarch64-none

Additionally, a specific system Python interpreter can often be requested with:

• <executable-path> e.g. /opt/homebrew/bin/python3
• <executable-name> e.g. mypython3
• <install-dir> e.g. /some/environment/

When the --python option is used, normal discovery rules apply but discovered interpreters are checked for compatibility with the request, e.g., if pypy is requested, fyn will first check if the virtual environment contains a PyPy interpreter then check if each executable in the path is a PyPy interpreter.

fyn supports discovering CPython, PyPy, and GraalPy interpreters. Unsupported interpreters will be skipped during discovery. If an unsupported interpreter implementation is requested, fyn will exit with an error.

Usage

fyn python [OPTIONS] <COMMAND>

Commands

fyn python list

List the available Python installations

fyn python install

Download and install Python versions

fyn python upgrade

Upgrade installed Python versions

fyn python find

Search for a Python installation

fyn python pin

Pin to a specific Python version

fyn python dir

Show the fyn Python installation directory

fyn python uninstall

Uninstall Python versions

fyn python install-shim

Install a python shim into the Python executable directory

fyn python update-shell

Ensure that the Python executable directory is on the PATH

fyn python list

List the available Python installations.

By default, installed Python versions and the downloads for latest available patch version of each supported Python major version are shown.

Use --managed-python to view only managed Python versions.

Use --no-managed-python to omit managed Python versions.

Use --all-versions to view all available patch versions.

Use --only-installed to omit available downloads.

Usage

fyn python list [OPTIONS] [REQUEST]

Arguments

REQUEST

A Python request to filter by.

See fyn python to view supported request formats.

Options

--all-arches, --all_architectures

List Python downloads for all architectures.

By default, only downloads for the current architecture are shown.

--all-platforms

List Python downloads for all platforms.

By default, only downloads for the current platform are shown.

--all-versions

List all Python versions, including old patch versions.

By default, only the latest patch version is shown for each minor version.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--only-downloads

Only show available Python downloads.

By default, installed distributions and available downloads for the current platform are shown.

--only-installed

Only show installed Python versions.

By default, installed distributions and available downloads for the current platform are shown.

--output-format output-format

Select the output format

[default: text]

Possible values:

• text: Plain text (for humans)
• json: JSON (for computers)

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python-downloads-json-url python-downloads-json-url

URL pointing to JSON of custom Python installations

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--show-urls

Show the URLs of available Python downloads.

By default, these display as <download available>.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn python install

Download and install Python versions.

Supports CPython and PyPy. CPython distributions are downloaded from the Astral python-build-standalone project. PyPy distributions are downloaded from python.org. The available Python versions are bundled with each fyn release. To install new Python versions, you may need upgrade fyn.

Python versions are installed into the fyn Python directory, which can be retrieved with fyn python dir.

By default, Python executables are added to a directory on the path with a minor version suffix, e.g., python3.13. To install python3 and python, use the --default flag. Use fyn python dir --bin to see the target directory.

Multiple Python versions may be requested.

See fyn help python to view supported request formats.

Usage

fyn python install [OPTIONS] [TARGETS]...

Arguments

TARGETS

The Python version(s) to install.

If not provided, the requested Python version(s) will be read from the UV_PYTHON environment variable then .python-versions or .python-version files. If none of the above are present, fyn will check if it has installed any Python versions. If not, it will install the latest stable version of Python.

See fyn python to view supported request formats.

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--compile-bytecode, --compile

Compile Python's standard library to bytecode after installation.

By default, fyn does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is important, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times and some additional disk space for faster start times.

When enabled, fyn will process the Python version's stdlib directory. It will ignore any compilation errors.

May also be set with the UV_COMPILE_BYTECODE environment variable.

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--default

Use as the default Python version.

By default, only a python{major}.{minor} executable is installed, e.g., python3.10. When the --default flag is used, python{major}, e.g., python3, and python executables are also installed.

Alternative Python variants will still include their tag. For example, installing 3.13+freethreaded with --default will include python3t and pythont instead of python3 and python.

If multiple Python versions are requested, fyn will exit with an error.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--force, -f

Replace existing Python executables during installation.

By default, fyn will refuse to replace executables that it does not manage.

Implies --reinstall.

--help, -h

Display the concise help for this command

--install-dir, -i install-dir

The directory to store the Python installation in.

If provided, UV_PYTHON_INSTALL_DIR will need to be set for subsequent operations for fyn to discover the Python installation.

See fyn python dir to view the current Python installation directory. Defaults to ~/.local/share/fyn/python.

May also be set with the UV_PYTHON_INSTALL_DIR environment variable.

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--mirror mirror

Set the URL to use as the source for downloading Python installations.

The provided URL will replace https://github.com/astral-sh/python-build-standalone/releases/download in, e.g., https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz.

Distributions can be read from a local directory by using the file:// URL scheme.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-bin

Do not install a Python executable into the bin directory.

This can also be set with UV_PYTHON_INSTALL_BIN=0.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-registry

Do not register the Python installation in the Windows registry.

This can also be set with UV_PYTHON_INSTALL_REGISTRY=0.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--pypy-mirror pypy-mirror

Set the URL to use as the source for downloading PyPy installations.

The provided URL will replace https://downloads.python.org/pypy in, e.g., https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2.

Distributions can be read from a local directory by using the file:// URL scheme.

--python-downloads-json-url python-downloads-json-url

URL pointing to JSON of custom Python installations

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--reinstall, -r

Reinstall the requested Python version, if it's already installed.

By default, fyn will exit successfully if the version is already installed.

--upgrade, -U

Upgrade existing Python installations to the latest patch version.

By default, fyn will not upgrade already-installed Python versions to newer patch releases. With --upgrade, fyn will upgrade to the latest available patch version for the specified minor version(s).

If the requested versions are not yet installed, fyn will install them.

This option is only supported for minor version requests, e.g., 3.12; fyn will exit with an error if a patch version, e.g., 3.12.2, is requested.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn python upgrade

Upgrade installed Python versions.

Upgrades versions to the latest supported patch release. Requires the python-upgrade preview feature.

A target Python minor version to upgrade may be provided, e.g., 3.13. Multiple versions may be provided to perform more than one upgrade.

If no target version is provided, then fyn will upgrade all managed CPython versions.

During an upgrade, fyn will not uninstall outdated patch versions.

When an upgrade is performed, virtual environments created by fyn will automatically use the new version. However, if the virtual environment was created before the upgrade functionality was added, it will continue to use the old Python version; to enable upgrades, the environment must be recreated.

Upgrades are not yet supported for alternative implementations, like PyPy.

Usage

fyn python upgrade [OPTIONS] [TARGETS]...

Arguments

TARGETS

The Python minor version(s) to upgrade.

If no target version is provided, then fyn will upgrade all managed CPython versions.

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--compile-bytecode, --compile

Compile Python's standard library to bytecode after installation.

By default, fyn does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is important, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times and some additional disk space for faster start times.

When enabled, fyn will process the Python version's stdlib directory. It will ignore any compilation errors.

May also be set with the UV_COMPILE_BYTECODE environment variable.

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--install-dir, -i install-dir

The directory Python installations are stored in.

If provided, UV_PYTHON_INSTALL_DIR will need to be set for subsequent operations for fyn to discover the Python installation.

See fyn python dir to view the current Python installation directory. Defaults to ~/.local/share/fyn/python.

May also be set with the UV_PYTHON_INSTALL_DIR environment variable.

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--mirror mirror

Set the URL to use as the source for downloading Python installations.

The provided URL will replace https://github.com/astral-sh/python-build-standalone/releases/download in, e.g., https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz.

Distributions can be read from a local directory by using the file:// URL scheme.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--pypy-mirror pypy-mirror

Set the URL to use as the source for downloading PyPy installations.

The provided URL will replace https://downloads.python.org/pypy in, e.g., https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2.

Distributions can be read from a local directory by using the file:// URL scheme.

--python-downloads-json-url python-downloads-json-url

URL pointing to JSON of custom Python installations

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--reinstall, -r

Reinstall the latest Python patch, if it's already installed.

By default, fyn will exit successfully if the latest patch is already installed.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn python find

Search for a Python installation.

Displays the path to the Python executable.

See fyn help python to view supported request formats and details on discovery behavior.

Usage

fyn python find [OPTIONS] [REQUEST]

Arguments

REQUEST

The Python request.

See fyn python to view supported request formats.

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-project, --no_workspace

Avoid discovering a project or workspace.

Otherwise, when no request is provided, the Python requirement of a project in the current directory or parent directories will be used.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python-downloads-json-url python-downloads-json-url

URL pointing to JSON of custom Python installations

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--resolve-links

Resolve symlinks in the output path.

When enabled, the output path will be canonicalized, resolving any symlinks.

--script script

Find the environment for a Python script, rather than the current project

--show-version

Show the Python version that would be used instead of the path to the interpreter

--system

Only find system Python interpreters.

By default, fyn will report the first Python interpreter it would use, including those in an active virtual environment or a virtual environment in the current working directory or any parent directory.

The --system option instructs fyn to skip virtual environment Python interpreters and restrict its search to the system path.

May also be set with the UV_SYSTEM_PYTHON environment variable.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn python pin

Pin to a specific Python version.

Writes the pinned Python version to a .python-version file, which is used by other fyn commands to determine the required Python version.

If no version is provided, fyn will look for an existing .python-version file and display the currently pinned version. If no .python-version file is found, fyn will exit with an error.

See fyn help python to view supported request formats.

Usage

fyn python pin [OPTIONS] [REQUEST]

Arguments

REQUEST

The Python version request.

fyn supports more formats than other tools that read .python-version files, i.e., pyenv. If compatibility with those tools is needed, only use version numbers instead of complex requests such as cpython@3.10.

If no request is provided, the currently pinned version will be shown.

See fyn python to view supported request formats.

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--global

Update the global Python version pin.

Writes the pinned Python version to a .python-version file in the fyn user configuration directory: XDG_CONFIG_HOME/fyn on Linux/macOS and %APPDATA%/fyn on Windows.

When a local Python version pin is not found in the working directory or an ancestor directory, this version will be used instead.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-project, --no-workspace

Avoid validating the Python pin is compatible with the project or workspace.

By default, a project or workspace is discovered in the current directory or any parent directory. If a workspace is found, the Python pin is validated against the workspace's requires-python constraint.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--resolved

Write the resolved Python interpreter path instead of the request.

Ensures that the exact same interpreter is used.

This option is usually not safe to use when committing the .python-version file to version control.

--rm

Remove the Python version pin

--upgrade, -U

Upgrade the Python pin to the latest compatible exact version.

If a request is provided, fyn upgrades that request. Otherwise, fyn upgrades the first entry from the discovered .python-version or .python-versions file.

When a project or workspace is discovered, the selected version must also satisfy its requires-python constraint.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn python dir

Show the fyn Python installation directory.

By default, Python installations are stored in the fyn data directory at $XDG_DATA_HOME/fyn/python or $HOME/.local/share/fyn/python on Unix and %APPDATA%\fyn\data\python on Windows.

The Python installation directory may be overridden with $UV_PYTHON_INSTALL_DIR.

To view the directory where fyn installs Python executables instead, use the --bin flag. The Python executable directory may be overridden with $UV_PYTHON_BIN_DIR. Note that Python executables are only installed when preview mode is enabled.

Usage

fyn python dir [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--bin

Show the directory into which fyn python will install Python executables.

Note that this directory is only used when installing Python with preview mode enabled.

The Python executable directory is determined according to the XDG standard and is derived from the following environment variables, in order of preference:

• $UV_PYTHON_BIN_DIR
• $XDG_BIN_HOME
• $XDG_DATA_HOME/../bin
• $HOME/.local/bin

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn python uninstall

Uninstall Python versions

Usage

fyn python uninstall [OPTIONS] <TARGETS>...

Arguments

TARGETS

The Python version(s) to uninstall.

See fyn python to view supported request formats.

Options

--all

Uninstall all managed Python versions

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--install-dir, -i install-dir

The directory where the Python was installed

May also be set with the UV_PYTHON_INSTALL_DIR environment variable.

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn python install-shim

Install a python shim into the Python executable directory.

The shim resolves the appropriate interpreter for the current directory before executing it, which makes a plain python command available on your shell PATH without pinning it to a single managed installation.

Usage

fyn python install-shim [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--force, -f

Replace an existing shim target.

By default, fyn refuses to replace an existing python executable unless it already matches the expected shim contents.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn python update-shell

Ensure that the Python executable directory is on the PATH.

If the Python executable directory is not present on the PATH, fyn will attempt to add it to the relevant shell configuration files.

If the shell configuration files already include a blurb to add the executable directory to the path, but the directory is not present on the PATH, fyn will exit with an error.

The Python executable directory is determined according to the XDG standard and can be retrieved with fyn python dir --bin.

Usage

fyn python update-shell [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn pip

Manage Python packages directly in an environment

Usage

fyn pip [OPTIONS] <COMMAND>

Commands

fyn pip compile

Compile a requirements.in file to a requirements.txt or pylock.toml file

fyn pip sync

Sync an environment with a requirements.txt or pylock.toml file

fyn pip install

Install packages into an environment

fyn pip download

Download distribution archives into a directory

fyn pip wheel

Build wheels into a directory

fyn pip index

Inspect package indexes

fyn pip upgrade

Upgrade packages in an environment

fyn pip uninstall

Uninstall packages from an environment

fyn pip freeze

List, in requirements format, packages installed in an environment

fyn pip list

List, in tabular format, packages installed in an environment

fyn pip show

Show information about one or more installed packages

fyn pip tree

Display the dependency tree for an environment

fyn pip check

Verify installed packages have compatible dependencies

fyn pip compile

Compile a requirements.in file to a requirements.txt or pylock.toml file

Usage

fyn pip compile [OPTIONS] <SRC_FILE|--group <GROUP>>

Arguments

SRC_FILE

Include the packages listed in the given files.

The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.

If a pyproject.toml, setup.py, or setup.cfg file is provided, fyn will extract the requirements for the relevant project.

If - is provided, then requirements will be read from stdin.

The order of the requirements files and the requirements in them is used to determine priority during resolution.

Options

--all-extras

Include all optional dependencies.

Only applies to pyproject.toml, setup.py, and setup.cfg sources.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--annotation-style annotation-style

The style of the annotation comments included in the output file, used to indicate the source of each package.

Defaults to split.

Possible values:

• line: Render the annotations on a single, comma-separated line
• split: Render each annotation on its own line

--build-constraints, --build-constraint, -b build-constraints

Constrain build dependencies using the given requirements files when building source distributions.

Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.

May also be set with the UV_BUILD_CONSTRAINT environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--constraints, --constraint, -c constraints

Constrain versions using the given requirements files.

Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.

This is equivalent to pip's --constraint option.

May also be set with the UV_CONSTRAINT environment variable.

--custom-compile-command custom-compile-command

The header comment to include at the top of the output file generated by fyn pip compile.

Used to reflect custom build scripts and commands that wrap fyn pip compile.

May also be set with the UV_CUSTOM_COMPILE_COMMAND environment variable.

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--emit-build-options

Include --no-binary and --only-binary entries in the generated output file

--emit-find-links

Include --find-links entries in the generated output file

--emit-index-annotation

Include comment annotations indicating the index used to resolve each package (e.g., # from https://pypi.org/simple)

--emit-index-url

Include --index-url and --extra-index-url entries in the generated output file

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--excludes, --exclude excludes

Exclude packages from resolution using the given requirements files.

Excludes files are requirements.txt-like files that specify packages to exclude from the resolution. When a package is excluded, it will be omitted from the dependency list entirely and its own dependencies will be ignored during the resolution phase. Excludes are unconditional in that requirement specifiers and markers are ignored; any package listed in the provided file will be omitted from all resolved environments.

May also be set with the UV_EXCLUDE environment variable.

--extra extra

Include optional dependencies from the specified extra name; may be provided more than once.

Only applies to pyproject.toml, setup.py, and setup.cfg sources.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--format format

The format in which the resolution should be output.

Supports both requirements.txt and pylock.toml (PEP 751) output formats.

fyn will infer the output format from the file extension of the output file, if provided. Otherwise, defaults to requirements.txt.

Possible values:

• requirements.txt: Export in requirements.txt format
• pylock.toml: Export in pylock.toml format

--generate-hashes

Include distribution hashes in the output file

--group group

Install the specified dependency group from a pyproject.toml.

If no path is provided, the pyproject.toml in the working directory is used.

May be provided multiple times.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

This option is only used when building source distributions.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-annotate

Exclude comment annotations indicating the source of each package

--no-binary no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Alias for --only-binary :all:.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-deps

Ignore package dependencies, instead only add those packages explicitly listed on the command line to the resulting requirements file

--no-emit-package, --unsafe-package no-emit-package

Specify a package to omit from the output resolution. Its dependencies will still be included in the resolution. Equivalent to pip-compile's --unsafe-package option

--no-header

Exclude the comment header at the top of the generated output file

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--no-strip-extras

Include extras in the output file.

By default, fyn strips extras, as any packages pulled in by the extras are already included as dependencies in the output file directly. Further, output files generated with --no-strip-extras cannot be used as constraints files in install and sync invocations.

--no-strip-markers

Include environment markers in the output file.

By default, fyn strips environment markers, as the resolution generated by compile is only guaranteed to be correct for the target environment.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--only-binary only-binary

Only use pre-built wheels; don't build source distributions.

When enabled, resolving will not run code from the given packages. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

--output-file, -o output-file

Write the compiled requirements to the given requirements.txt or pylock.toml file.

If the file already exists, the existing versions will be preferred when resolving dependencies, unless --upgrade is also specified.

--overrides, --override overrides

Override versions using the given requirements files.

Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.

While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.

May also be set with the UV_OVERRIDE environment variable.

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to use during resolution.

A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.

The interpreter is also used to determine the default minimum Python version, unless --python-version is provided.

This option respects UV_PYTHON, but when set via environment variable, it is overridden by --python-version.

See fyn python for details on Python discovery and supported request formats.

--python-platform python-platform

The platform for which requirements should be resolved.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.

Possible values:

• windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
• linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
• macos: An alias for aarch64-apple-darwin, the default target for macOS
• x86_64-pc-windows-msvc: A 64-bit x86 Windows target
• aarch64-pc-windows-msvc: An ARM64 Windows target
• i686-pc-windows-msvc: A 32-bit x86 Windows target
• x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
• aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
• x86_64-apple-darwin: An x86 macOS target
• aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
• aarch64-unknown-linux-musl: An ARM64 Linux target
• x86_64-unknown-linux-musl: An x86_64 Linux target
• riscv64-unknown-linux: A RISCV64 Linux target
• x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
• x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
• x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
• x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
• x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
• x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
• x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
• x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
• x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
• x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
• x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
• x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
• x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
• aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
• aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
• aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
• aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
• aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
• aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
• aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
• aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
• aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
• aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
• aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
• aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
• aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
• aarch64-linux-android: An ARM64 Android target
• x86_64-linux-android: An x86_64 Android target
• wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
• arm64-apple-ios: An ARM64 target for iOS device
• arm64-apple-ios-simulator: An ARM64 target for iOS simulator
• x86_64-apple-ios-simulator: An x86_64 target for iOS simulator

--python-version python-version

The Python version to use for resolution.

For example, 3.8 or 3.8.17.

Defaults to the version of the Python interpreter used for resolution.

Defines the minimum Python version that must be supported by the resolved requirements.

If a patch version is omitted, the minimum patch version is assumed. For example, 3.8 is mapped to 3.8.0.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--system

Install packages into the system Python environment.

By default, fyn uses the virtual environment in the current working directory or any parent directory, falling back to searching for a Python executable in PATH. The --system option instructs fyn to avoid using a virtual environment Python and restrict its search to the system path.

May also be set with the UV_SYSTEM_PYTHON environment variable.

--torch-backend torch-backend

The backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto).

When set, fyn will ignore the configured index URLs for packages in the PyTorch ecosystem, and will instead use the defined backend.

For example, when set to cpu, fyn will use the CPU-only PyTorch index; when set to cu126, fyn will use the PyTorch index for CUDA 12.6.

The auto mode will attempt to detect the appropriate PyTorch index based on the currently installed CUDA drivers.

This option is in preview and may change in any future release.

May also be set with the UV_TORCH_BACKEND environment variable.

Possible values:

• auto: Select the appropriate PyTorch index based on the operating system and CUDA driver version
• cpu: Use the CPU-only PyTorch index
• cu130: Use the PyTorch index for CUDA 13.0
• cu129: Use the PyTorch index for CUDA 12.9
• cu128: Use the PyTorch index for CUDA 12.8
• cu126: Use the PyTorch index for CUDA 12.6
• cu125: Use the PyTorch index for CUDA 12.5
• cu124: Use the PyTorch index for CUDA 12.4
• cu123: Use the PyTorch index for CUDA 12.3
• cu122: Use the PyTorch index for CUDA 12.2
• cu121: Use the PyTorch index for CUDA 12.1
• cu120: Use the PyTorch index for CUDA 12.0
• cu118: Use the PyTorch index for CUDA 11.8
• cu117: Use the PyTorch index for CUDA 11.7
• cu116: Use the PyTorch index for CUDA 11.6
• cu115: Use the PyTorch index for CUDA 11.5
• cu114: Use the PyTorch index for CUDA 11.4
• cu113: Use the PyTorch index for CUDA 11.3
• cu112: Use the PyTorch index for CUDA 11.2
• cu111: Use the PyTorch index for CUDA 11.1
• cu110: Use the PyTorch index for CUDA 11.0
• cu102: Use the PyTorch index for CUDA 10.2
• cu101: Use the PyTorch index for CUDA 10.1
• cu100: Use the PyTorch index for CUDA 10.0
• cu92: Use the PyTorch index for CUDA 9.2
• cu91: Use the PyTorch index for CUDA 9.1
• cu90: Use the PyTorch index for CUDA 9.0
• cu80: Use the PyTorch index for CUDA 8.0
• rocm7.1: Use the PyTorch index for ROCm 7.1
• rocm7.0: Use the PyTorch index for ROCm 7.0
• rocm6.4: Use the PyTorch index for ROCm 6.4
• rocm6.3: Use the PyTorch index for ROCm 6.3
• rocm6.2.4: Use the PyTorch index for ROCm 6.2.4
• rocm6.2: Use the PyTorch index for ROCm 6.2
• rocm6.1: Use the PyTorch index for ROCm 6.1
• rocm6.0: Use the PyTorch index for ROCm 6.0
• rocm5.7: Use the PyTorch index for ROCm 5.7
• rocm5.6: Use the PyTorch index for ROCm 5.6
• rocm5.5: Use the PyTorch index for ROCm 5.5
• rocm5.4.2: Use the PyTorch index for ROCm 5.4.2
• rocm5.4: Use the PyTorch index for ROCm 5.4
• rocm5.3: Use the PyTorch index for ROCm 5.3
• rocm5.2: Use the PyTorch index for ROCm 5.2
• rocm5.1.1: Use the PyTorch index for ROCm 5.1.1
• rocm4.2: Use the PyTorch index for ROCm 4.2
• rocm4.1: Use the PyTorch index for ROCm 4.1
• rocm4.0.1: Use the PyTorch index for ROCm 4.0.1
• xpu: Use the PyTorch index for Intel XPU

--universal

Perform a universal resolution, attempting to generate a single requirements.txt output file that is compatible with all operating systems, architectures, and Python implementations.

In universal mode, the current Python version (or user-provided --python-version) will be treated as a lower bound. For example, --universal --python-version 3.7 would produce a universal resolution for Python 3.7 and later.

Implies --no-strip-markers.

--upgrade, -U

Allow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh

--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn pip sync

Sync an environment with a requirements.txt or pylock.toml file.

When syncing an environment, any packages not listed in the requirements.txt or pylock.toml file will be removed. To retain extraneous packages, use fyn pip install instead.

The input file is presumed to be the output of a pip compile or fyn export operation, in which it will include all transitive dependencies. If transitive dependencies are not present in the file, they will not be installed. Use --strict to warn if any transitive dependencies are missing.

Usage

fyn pip sync [OPTIONS] <SRC_FILE>...

Arguments

SRC_FILE

Include the packages listed in the given files.

The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.

If a pyproject.toml, setup.py, or setup.cfg file is provided, fyn will extract the requirements for the relevant project.

If - is provided, then requirements will be read from stdin.

Options

--all-extras

Include all optional dependencies.

Only applies to pylock.toml, pyproject.toml, setup.py, and setup.cfg sources.

--allow-empty-requirements

Allow sync of empty requirements, which will clear the environment of all packages

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--break-system-packages

Allow fyn to modify an EXTERNALLY-MANAGED Python installation.

WARNING: --break-system-packages is intended for use in continuous integration (CI) environments, when installing into Python installations that are managed by an external package manager, like apt. It should be used with caution, as such Python installations explicitly recommend against modifications by other package managers (like fyn or pip).

May also be set with the UV_BREAK_SYSTEM_PACKAGES environment variable.

--build-constraints, --build-constraint, -b build-constraints

Constrain build dependencies using the given requirements files when building source distributions.

Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.

May also be set with the UV_BUILD_CONSTRAINT environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--compile-bytecode, --compile

Compile Python files to bytecode after installation.

By default, fyn does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, fyn will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

May also be set with the UV_COMPILE_BYTECODE environment variable.

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--constraints, --constraint, -c constraints

Constrain versions using the given requirements files.

Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.

This is equivalent to pip's --constraint option.

May also be set with the UV_CONSTRAINT environment variable.

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--dry-run

Perform a dry run, i.e., don't actually install anything but resolve the dependencies and print the resulting plan

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra extra

Include optional dependencies from the specified extra name; may be provided more than once.

Only applies to pylock.toml, pyproject.toml, setup.py, and setup.cfg sources.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--group group

Install the specified dependency group from a pylock.toml or pyproject.toml.

If no path is provided, the pylock.toml or pyproject.toml in the working directory is used.

May be provided multiple times.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-allow-empty-requirements

--no-binary no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

--no-break-system-packages

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Alias for --only-binary :all:.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--no-verify-hashes

Disable validation of hashes in the requirements file.

By default, fyn will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash. To enforce hash validation, use --require-hashes.

May also be set with the UV_NO_VERIFY_HASHES environment variable.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--only-binary only-binary

Only use pre-built wheels; don't build source distributions.

When enabled, resolving will not run code from the given packages. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

--prefix prefix

Install packages into lib, bin, and other top-level folders under the specified directory, as if a virtual environment were present at that location.

In general, prefer the use of --python to install into an alternate environment, as scripts and other artifacts installed via --prefix will reference the installing interpreter, rather than any interpreter added to the --prefix directory, rendering them non-portable.

Unlike other install operations, this command does not require discovery of an existing Python environment and only searches for a Python interpreter to use for package resolution. If a suitable Python interpreter cannot be found, fyn will install one. To disable this, add --no-python-downloads.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter into which packages should be installed.

By default, syncing requires a virtual environment. A path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--python-platform python-platform

The platform for which requirements should be installed.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.

WARNING: When specified, fyn will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.

Possible values:

• windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
• linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
• macos: An alias for aarch64-apple-darwin, the default target for macOS
• x86_64-pc-windows-msvc: A 64-bit x86 Windows target
• aarch64-pc-windows-msvc: An ARM64 Windows target
• i686-pc-windows-msvc: A 32-bit x86 Windows target
• x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
• aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
• x86_64-apple-darwin: An x86 macOS target
• aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
• aarch64-unknown-linux-musl: An ARM64 Linux target
• x86_64-unknown-linux-musl: An x86_64 Linux target
• riscv64-unknown-linux: A RISCV64 Linux target
• x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
• x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
• x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
• x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
• x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
• x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
• x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
• x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
• x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
• x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
• x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
• x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
• x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
• aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
• aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
• aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
• aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
• aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
• aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
• aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
• aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
• aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
• aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
• aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
• aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
• aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
• aarch64-linux-android: An ARM64 Android target
• x86_64-linux-android: An x86_64 Android target
• wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
• arm64-apple-ios: An ARM64 target for iOS device
• arm64-apple-ios-simulator: An ARM64 target for iOS simulator
• x86_64-apple-ios-simulator: An x86_64 target for iOS simulator

--python-version python-version

The minimum Python version that should be supported by the requirements (e.g., 3.7 or 3.7.9).

If a patch version is omitted, the minimum patch version is assumed. For example, 3.7 is mapped to 3.7.0.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall, --force-reinstall

Reinstall all packages, regardless of whether they're already installed. Implies --refresh

--reinstall-package reinstall-package

Reinstall a specific package, regardless of whether it's already installed. Implies --refresh-package

--require-hashes

Require a matching hash for each requirement.

By default, fyn will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash.

When --require-hashes is enabled, all requirements must include a hash or set of hashes, and all requirements must either be pinned to exact versions (e.g., ==1.0.0), or be specified via direct URL.

Hash-checking mode introduces a number of additional constraints:

• Git dependencies are not supported. - Editable installations are not supported. - Local dependencies are not supported, unless they point to a specific wheel (.whl) or source archive (.zip, .tar.gz), as opposed to a directory.

May also be set with the UV_REQUIRE_HASHES environment variable.

--strict

Validate the Python environment after completing the installation, to detect packages with missing dependencies or other issues

--system

Install packages into the system Python environment.

By default, fyn installs into the virtual environment in the current working directory or any parent directory. The --system option instructs fyn to instead use the first Python found in the system PATH.

WARNING: --system is intended for use in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

May also be set with the UV_SYSTEM_PYTHON environment variable.

--target, -t target

Install packages into the specified directory, rather than into the virtual or system Python environment. The packages will be installed at the top-level of the directory.

Unlike other install operations, this command does not require discovery of an existing Python environment and only searches for a Python interpreter to use for package resolution. If a suitable Python interpreter cannot be found, fyn will install one. To disable this, add --no-python-downloads.

--torch-backend torch-backend

The backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto).

When set, fyn will ignore the configured index URLs for packages in the PyTorch ecosystem, and will instead use the defined backend.

For example, when set to cpu, fyn will use the CPU-only PyTorch index; when set to cu126, fyn will use the PyTorch index for CUDA 12.6.

The auto mode will attempt to detect the appropriate PyTorch index based on the currently installed CUDA drivers.

This option is in preview and may change in any future release.

May also be set with the UV_TORCH_BACKEND environment variable.

Possible values:

• auto: Select the appropriate PyTorch index based on the operating system and CUDA driver version
• cpu: Use the CPU-only PyTorch index
• cu130: Use the PyTorch index for CUDA 13.0
• cu129: Use the PyTorch index for CUDA 12.9
• cu128: Use the PyTorch index for CUDA 12.8
• cu126: Use the PyTorch index for CUDA 12.6
• cu125: Use the PyTorch index for CUDA 12.5
• cu124: Use the PyTorch index for CUDA 12.4
• cu123: Use the PyTorch index for CUDA 12.3
• cu122: Use the PyTorch index for CUDA 12.2
• cu121: Use the PyTorch index for CUDA 12.1
• cu120: Use the PyTorch index for CUDA 12.0
• cu118: Use the PyTorch index for CUDA 11.8
• cu117: Use the PyTorch index for CUDA 11.7
• cu116: Use the PyTorch index for CUDA 11.6
• cu115: Use the PyTorch index for CUDA 11.5
• cu114: Use the PyTorch index for CUDA 11.4
• cu113: Use the PyTorch index for CUDA 11.3
• cu112: Use the PyTorch index for CUDA 11.2
• cu111: Use the PyTorch index for CUDA 11.1
• cu110: Use the PyTorch index for CUDA 11.0
• cu102: Use the PyTorch index for CUDA 10.2
• cu101: Use the PyTorch index for CUDA 10.1
• cu100: Use the PyTorch index for CUDA 10.0
• cu92: Use the PyTorch index for CUDA 9.2
• cu91: Use the PyTorch index for CUDA 9.1
• cu90: Use the PyTorch index for CUDA 9.0
• cu80: Use the PyTorch index for CUDA 8.0
• rocm7.1: Use the PyTorch index for ROCm 7.1
• rocm7.0: Use the PyTorch index for ROCm 7.0
• rocm6.4: Use the PyTorch index for ROCm 6.4
• rocm6.3: Use the PyTorch index for ROCm 6.3
• rocm6.2.4: Use the PyTorch index for ROCm 6.2.4
• rocm6.2: Use the PyTorch index for ROCm 6.2
• rocm6.1: Use the PyTorch index for ROCm 6.1
• rocm6.0: Use the PyTorch index for ROCm 6.0
• rocm5.7: Use the PyTorch index for ROCm 5.7
• rocm5.6: Use the PyTorch index for ROCm 5.6
• rocm5.5: Use the PyTorch index for ROCm 5.5
• rocm5.4.2: Use the PyTorch index for ROCm 5.4.2
• rocm5.4: Use the PyTorch index for ROCm 5.4
• rocm5.3: Use the PyTorch index for ROCm 5.3
• rocm5.2: Use the PyTorch index for ROCm 5.2
• rocm5.1.1: Use the PyTorch index for ROCm 5.1.1
• rocm4.2: Use the PyTorch index for ROCm 4.2
• rocm4.1: Use the PyTorch index for ROCm 4.1
• rocm4.0.1: Use the PyTorch index for ROCm 4.0.1
• xpu: Use the PyTorch index for Intel XPU

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn pip install

Install packages into an environment

Usage

fyn pip install [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>|--editable <EDITABLE>|--group <GROUP>>

Arguments

PACKAGE

Install all listed packages.

The order of the packages is used to determine priority during resolution.

Options

--all-extras

Include all optional dependencies.

Only applies to pylock.toml, pyproject.toml, setup.py, and setup.cfg sources.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--break-system-packages

Allow fyn to modify an EXTERNALLY-MANAGED Python installation.

WARNING: --break-system-packages is intended for use in continuous integration (CI) environments, when installing into Python installations that are managed by an external package manager, like apt. It should be used with caution, as such Python installations explicitly recommend against modifications by other package managers (like fyn or pip).

May also be set with the UV_BREAK_SYSTEM_PACKAGES environment variable.

--build-constraints, --build-constraint, -b build-constraints

Constrain build dependencies using the given requirements files when building source distributions.

Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.

May also be set with the UV_BUILD_CONSTRAINT environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--compile-bytecode, --compile

Compile Python files to bytecode after installation.

By default, fyn does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, fyn will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

May also be set with the UV_COMPILE_BYTECODE environment variable.

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--constraints, --constraint, -c constraints

Constrain versions using the given requirements files.

Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.

This is equivalent to pip's --constraint option.

May also be set with the UV_CONSTRAINT environment variable.

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--dry-run

Perform a dry run, i.e., don't actually install anything but resolve the dependencies and print the resulting plan

--editable, -e editable

Install the editable package based on the provided local file path

--exact

Perform an exact sync, removing extraneous packages.

By default, installing will make the minimum necessary changes to satisfy the requirements. When enabled, fyn will update the environment to exactly match the requirements, removing packages that are not included in the requirements.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--excludes, --exclude excludes

Exclude packages from resolution using the given requirements files.

Excludes files are requirements.txt-like files that specify packages to exclude from the resolution. When a package is excluded, it will be omitted from the dependency list entirely and its own dependencies will be ignored during the resolution phase. Excludes are unconditional in that requirement specifiers and markers are ignored; any package listed in the provided file will be omitted from all resolved environments.

May also be set with the UV_EXCLUDE environment variable.

--extra extra

Include optional dependencies from the specified extra name; may be provided more than once.

Only applies to pylock.toml, pyproject.toml, setup.py, and setup.cfg sources.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--group group

Install the specified dependency group from a pylock.toml or pyproject.toml.

If no path is provided, the pylock.toml or pyproject.toml in the working directory is used.

May be provided multiple times.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

--no-break-system-packages

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Alias for --only-binary :all:.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-deps

Ignore package dependencies, instead only installing those packages explicitly listed on the command line or in the requirements files

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--no-verify-hashes

Disable validation of hashes in the requirements file.

By default, fyn will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash. To enforce hash validation, use --require-hashes.

May also be set with the UV_NO_VERIFY_HASHES environment variable.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--only-binary only-binary

Only use pre-built wheels; don't build source distributions.

When enabled, resolving will not run code from the given packages. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

--overrides, --override overrides

Override versions using the given requirements files.

Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.

While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.

May also be set with the UV_OVERRIDE environment variable.

--prefix prefix

Install packages into lib, bin, and other top-level folders under the specified directory, as if a virtual environment were present at that location.

In general, prefer the use of --python to install into an alternate environment, as scripts and other artifacts installed via --prefix will reference the installing interpreter, rather than any interpreter added to the --prefix directory, rendering them non-portable.

Unlike other install operations, this command does not require discovery of an existing Python environment and only searches for a Python interpreter to use for package resolution. If a suitable Python interpreter cannot be found, fyn will install one. To disable this, add --no-python-downloads.

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter into which packages should be installed.

By default, installation requires a virtual environment. A path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--python-platform python-platform

The platform for which requirements should be installed.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.

WARNING: When specified, fyn will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.

Possible values:

• windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
• linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
• macos: An alias for aarch64-apple-darwin, the default target for macOS
• x86_64-pc-windows-msvc: A 64-bit x86 Windows target
• aarch64-pc-windows-msvc: An ARM64 Windows target
• i686-pc-windows-msvc: A 32-bit x86 Windows target
• x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
• aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
• x86_64-apple-darwin: An x86 macOS target
• aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
• aarch64-unknown-linux-musl: An ARM64 Linux target
• x86_64-unknown-linux-musl: An x86_64 Linux target
• riscv64-unknown-linux: A RISCV64 Linux target
• x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
• x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
• x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
• x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
• x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
• x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
• x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
• x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
• x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
• x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
• x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
• x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
• x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
• aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
• aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
• aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
• aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
• aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
• aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
• aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
• aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
• aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
• aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
• aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
• aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
• aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
• aarch64-linux-android: An ARM64 Android target
• x86_64-linux-android: An x86_64 Android target
• wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
• arm64-apple-ios: An ARM64 target for iOS device
• arm64-apple-ios-simulator: An ARM64 target for iOS simulator
• x86_64-apple-ios-simulator: An x86_64 target for iOS simulator

--python-version python-version

The minimum Python version that should be supported by the requirements (e.g., 3.7 or 3.7.9).

If a patch version is omitted, the minimum patch version is assumed. For example, 3.7 is mapped to 3.7.0.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall, --force-reinstall

Reinstall all packages, regardless of whether they're already installed. Implies --refresh

--reinstall-package reinstall-package

Reinstall a specific package, regardless of whether it's already installed. Implies --refresh-package

--require-hashes

Require a matching hash for each requirement.

By default, fyn will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash.

When --require-hashes is enabled, all requirements must include a hash or set of hashes, and all requirements must either be pinned to exact versions (e.g., ==1.0.0), or be specified via direct URL.

Hash-checking mode introduces a number of additional constraints:

• Git dependencies are not supported. - Editable installations are not supported. - Local dependencies are not supported, unless they point to a specific wheel (.whl) or source archive (.zip, .tar.gz), as opposed to a directory.

May also be set with the UV_REQUIRE_HASHES environment variable.

--requirements, --requirement, -r requirements

Install the packages listed in the given files.

The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.

If a pyproject.toml, setup.py, or setup.cfg file is provided, fyn will extract the requirements for the relevant project.

If - is provided, then requirements will be read from stdin.

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--strict

Validate the Python environment after completing the installation, to detect packages with missing dependencies or other issues

--system

Install packages into the system Python environment.

By default, fyn installs into the virtual environment in the current working directory or any parent directory. The --system option instructs fyn to instead use the first Python found in the system PATH.

WARNING: --system is intended for use in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

May also be set with the UV_SYSTEM_PYTHON environment variable.

--target, -t target

Install packages into the specified directory, rather than into the virtual or system Python environment. The packages will be installed at the top-level of the directory.

Unlike other install operations, this command does not require discovery of an existing Python environment and only searches for a Python interpreter to use for package resolution. If a suitable Python interpreter cannot be found, fyn will install one. To disable this, add --no-python-downloads.

--torch-backend torch-backend

The backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto)

When set, fyn will ignore the configured index URLs for packages in the PyTorch ecosystem, and will instead use the defined backend.

For example, when set to cpu, fyn will use the CPU-only PyTorch index; when set to cu126, fyn will use the PyTorch index for CUDA 12.6.

The auto mode will attempt to detect the appropriate PyTorch index based on the currently installed CUDA drivers.

This option is in preview and may change in any future release.

May also be set with the UV_TORCH_BACKEND environment variable.

Possible values:

• auto: Select the appropriate PyTorch index based on the operating system and CUDA driver version
• cpu: Use the CPU-only PyTorch index
• cu130: Use the PyTorch index for CUDA 13.0
• cu129: Use the PyTorch index for CUDA 12.9
• cu128: Use the PyTorch index for CUDA 12.8
• cu126: Use the PyTorch index for CUDA 12.6
• cu125: Use the PyTorch index for CUDA 12.5
• cu124: Use the PyTorch index for CUDA 12.4
• cu123: Use the PyTorch index for CUDA 12.3
• cu122: Use the PyTorch index for CUDA 12.2
• cu121: Use the PyTorch index for CUDA 12.1
• cu120: Use the PyTorch index for CUDA 12.0
• cu118: Use the PyTorch index for CUDA 11.8
• cu117: Use the PyTorch index for CUDA 11.7
• cu116: Use the PyTorch index for CUDA 11.6
• cu115: Use the PyTorch index for CUDA 11.5
• cu114: Use the PyTorch index for CUDA 11.4
• cu113: Use the PyTorch index for CUDA 11.3
• cu112: Use the PyTorch index for CUDA 11.2
• cu111: Use the PyTorch index for CUDA 11.1
• cu110: Use the PyTorch index for CUDA 11.0
• cu102: Use the PyTorch index for CUDA 10.2
• cu101: Use the PyTorch index for CUDA 10.1
• cu100: Use the PyTorch index for CUDA 10.0
• cu92: Use the PyTorch index for CUDA 9.2
• cu91: Use the PyTorch index for CUDA 9.1
• cu90: Use the PyTorch index for CUDA 9.0
• cu80: Use the PyTorch index for CUDA 8.0
• rocm7.1: Use the PyTorch index for ROCm 7.1
• rocm7.0: Use the PyTorch index for ROCm 7.0
• rocm6.4: Use the PyTorch index for ROCm 6.4
• rocm6.3: Use the PyTorch index for ROCm 6.3
• rocm6.2.4: Use the PyTorch index for ROCm 6.2.4
• rocm6.2: Use the PyTorch index for ROCm 6.2
• rocm6.1: Use the PyTorch index for ROCm 6.1
• rocm6.0: Use the PyTorch index for ROCm 6.0
• rocm5.7: Use the PyTorch index for ROCm 5.7
• rocm5.6: Use the PyTorch index for ROCm 5.6
• rocm5.5: Use the PyTorch index for ROCm 5.5
• rocm5.4.2: Use the PyTorch index for ROCm 5.4.2
• rocm5.4: Use the PyTorch index for ROCm 5.4
• rocm5.3: Use the PyTorch index for ROCm 5.3
• rocm5.2: Use the PyTorch index for ROCm 5.2
• rocm5.1.1: Use the PyTorch index for ROCm 5.1.1
• rocm4.2: Use the PyTorch index for ROCm 4.2
• rocm4.1: Use the PyTorch index for ROCm 4.1
• rocm4.0.1: Use the PyTorch index for ROCm 4.0.1
• xpu: Use the PyTorch index for Intel XPU

--upgrade, -U

Allow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh

--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--user

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn pip download

Download distribution archives into a directory

Usage

fyn pip download [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>|--group <GROUP>>

Arguments

PACKAGE

Download all listed packages.

The order of the packages is used to determine priority during resolution.

Options

--all-extras

Include all optional dependencies.

Only applies to pyproject.toml, setup.py, and setup.cfg sources.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--build-constraints, --build-constraint, -b build-constraints

Constrain build dependencies using the given requirements files when building source distributions.

Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.

May also be set with the UV_BUILD_CONSTRAINT environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--constraints, --constraint, -c constraints

Constrain versions using the given requirements files.

Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.

This is equivalent to pip's --constraint option.

May also be set with the UV_CONSTRAINT environment variable.

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--dest, -d dest

Store downloaded distributions in the given directory.

Defaults to the current working directory.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--excludes, --exclude excludes

Exclude packages from resolution using the given requirements files.

Excludes files are requirements.txt-like files that specify packages to exclude from the resolution. When a package is excluded, it will be omitted from the dependency list entirely and its own dependencies will be ignored during the resolution phase. Excludes are unconditional in that requirement specifiers and markers are ignored; any package listed in the provided file will be omitted from all resolved environments.

May also be set with the UV_EXCLUDE environment variable.

--extra extra

Include optional dependencies from the specified extra name; may be provided more than once.

Only applies to pyproject.toml, setup.py, and setup.cfg sources.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--group group

Download the specified dependency group from a pyproject.toml.

If no path is provided, the pyproject.toml in the working directory is used.

May be provided multiple times.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

This option is only used when building source distributions.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary no-binary

Don't download pre-built wheels.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Alias for --only-binary :all:.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-deps

Ignore package dependencies, instead only downloading those packages explicitly listed on the command line or in the requirements files

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--only-binary only-binary

Only download pre-built wheels; don't build source distributions.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

--overrides, --override overrides

Override versions using the given requirements files.

Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.

While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.

May also be set with the UV_OVERRIDE environment variable.

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to use during resolution.

A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.

The interpreter is also used to determine the default minimum Python version, unless --python-version is provided.

This option respects UV_PYTHON, but when set via environment variable, it is overridden by --python-version.

See fyn python for details on Python discovery and supported request formats.

--python-platform python-platform

The platform for which requirements should be downloaded.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

Possible values:

• windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
• linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
• macos: An alias for aarch64-apple-darwin, the default target for macOS
• x86_64-pc-windows-msvc: A 64-bit x86 Windows target
• aarch64-pc-windows-msvc: An ARM64 Windows target
• i686-pc-windows-msvc: A 32-bit x86 Windows target
• x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
• aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
• x86_64-apple-darwin: An x86 macOS target
• aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
• aarch64-unknown-linux-musl: An ARM64 Linux target
• x86_64-unknown-linux-musl: An x86_64 Linux target
• riscv64-unknown-linux: A RISCV64 Linux target
• x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
• x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
• x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
• x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
• x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
• x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
• x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
• x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
• x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
• x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
• x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
• x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
• x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
• aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
• aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
• aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
• aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
• aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
• aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
• aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
• aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
• aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
• aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
• aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
• aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
• aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
• aarch64-linux-android: An ARM64 Android target
• x86_64-linux-android: An x86_64 Android target
• wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
• arm64-apple-ios: An ARM64 target for iOS device
• arm64-apple-ios-simulator: An ARM64 target for iOS simulator
• x86_64-apple-ios-simulator: An x86_64 target for iOS simulator

--python-version python-version

The minimum Python version that should be supported by the downloaded requirements (e.g., 3.7 or 3.7.9).

If a patch version is omitted, the minimum patch version is assumed. For example, 3.7 is mapped to 3.7.0.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--requirements, --requirement, -r requirements

Download the packages listed in the given files.

The following formats are supported: requirements.txt, .py files with inline metadata, pyproject.toml, setup.py, and setup.cfg.

If a pyproject.toml, setup.py, or setup.cfg file is provided, fyn will extract the requirements for the relevant project.

If - is provided, then requirements will be read from stdin.

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--system

Use a system Python interpreter during resolution.

By default, fyn uses a virtual environment in the current working directory or any parent directory, falling back to searching for a Python executable in PATH. The --system option instructs fyn to avoid using a virtual environment Python and restrict its search to the system path.

May also be set with the UV_SYSTEM_PYTHON environment variable.

--torch-backend torch-backend

The backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto).

When set, fyn will ignore the configured index URLs for packages in the PyTorch ecosystem, and will instead use the defined backend.

The auto mode will attempt to detect the appropriate PyTorch index based on the currently installed CUDA drivers.

This option is in preview and may change in any future release.

May also be set with the UV_TORCH_BACKEND environment variable.

Possible values:

• auto: Select the appropriate PyTorch index based on the operating system and CUDA driver version
• cpu: Use the CPU-only PyTorch index
• cu130: Use the PyTorch index for CUDA 13.0
• cu129: Use the PyTorch index for CUDA 12.9
• cu128: Use the PyTorch index for CUDA 12.8
• cu126: Use the PyTorch index for CUDA 12.6
• cu125: Use the PyTorch index for CUDA 12.5
• cu124: Use the PyTorch index for CUDA 12.4
• cu123: Use the PyTorch index for CUDA 12.3
• cu122: Use the PyTorch index for CUDA 12.2
• cu121: Use the PyTorch index for CUDA 12.1
• cu120: Use the PyTorch index for CUDA 12.0
• cu118: Use the PyTorch index for CUDA 11.8
• cu117: Use the PyTorch index for CUDA 11.7
• cu116: Use the PyTorch index for CUDA 11.6
• cu115: Use the PyTorch index for CUDA 11.5
• cu114: Use the PyTorch index for CUDA 11.4
• cu113: Use the PyTorch index for CUDA 11.3
• cu112: Use the PyTorch index for CUDA 11.2
• cu111: Use the PyTorch index for CUDA 11.1
• cu110: Use the PyTorch index for CUDA 11.0
• cu102: Use the PyTorch index for CUDA 10.2
• cu101: Use the PyTorch index for CUDA 10.1
• cu100: Use the PyTorch index for CUDA 10.0
• cu92: Use the PyTorch index for CUDA 9.2
• cu91: Use the PyTorch index for CUDA 9.1
• cu90: Use the PyTorch index for CUDA 9.0
• cu80: Use the PyTorch index for CUDA 8.0
• rocm7.1: Use the PyTorch index for ROCm 7.1
• rocm7.0: Use the PyTorch index for ROCm 7.0
• rocm6.4: Use the PyTorch index for ROCm 6.4
• rocm6.3: Use the PyTorch index for ROCm 6.3
• rocm6.2.4: Use the PyTorch index for ROCm 6.2.4
• rocm6.2: Use the PyTorch index for ROCm 6.2
• rocm6.1: Use the PyTorch index for ROCm 6.1
• rocm6.0: Use the PyTorch index for ROCm 6.0
• rocm5.7: Use the PyTorch index for ROCm 5.7
• rocm5.6: Use the PyTorch index for ROCm 5.6
• rocm5.5: Use the PyTorch index for ROCm 5.5
• rocm5.4.2: Use the PyTorch index for ROCm 5.4.2
• rocm5.4: Use the PyTorch index for ROCm 5.4
• rocm5.3: Use the PyTorch index for ROCm 5.3
• rocm5.2: Use the PyTorch index for ROCm 5.2
• rocm5.1.1: Use the PyTorch index for ROCm 5.1.1
• rocm4.2: Use the PyTorch index for ROCm 4.2
• rocm4.1: Use the PyTorch index for ROCm 4.1
• rocm4.0.1: Use the PyTorch index for ROCm 4.0.1
• xpu: Use the PyTorch index for Intel XPU

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn pip wheel

Build wheels into a directory

Usage

fyn pip wheel [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>|--group <GROUP>>

Arguments

PACKAGE

Build wheels for all listed packages.

The order of the packages is used to determine priority during resolution.

Options

--all-extras

Include all optional dependencies.

Only applies to pyproject.toml, setup.py, and setup.cfg sources.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--build-constraints, --build-constraint, -b build-constraints

Constrain build dependencies using the given requirements files when building source distributions

May also be set with the UV_BUILD_CONSTRAINT environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--constraints, --constraint, -c constraints

Constrain versions using the given requirements files

May also be set with the UV_CONSTRAINT environment variable.

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--excludes, --exclude excludes

Exclude packages from resolution using the given requirements files

May also be set with the UV_EXCLUDE environment variable.

--extra extra

Include optional dependencies from the specified extra name; may be provided more than once.

Only applies to pyproject.toml, setup.py, and setup.cfg sources.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--group group

Build wheels for the specified dependency group from a pyproject.toml.

If no path is provided, the pyproject.toml in the working directory is used.

May be provided multiple times.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

This option is only used when building source distributions.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary no-binary

Don't download pre-built wheels.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

--no-build

Don't build source distributions.

Alias for --only-binary :all:.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-deps

Ignore package dependencies, instead only building wheels for those packages explicitly listed on the command line or in the requirements files

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--only-binary only-binary

Only download pre-built wheels; don't build source distributions.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

--overrides, --override overrides

Override versions using the given requirements files

May also be set with the UV_OVERRIDE environment variable.

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to use during resolution and wheel builds.

This option respects UV_PYTHON, but when set via environment variable, it is overridden by --python-version.

See fyn python for details on Python discovery and supported request formats.

--python-platform python-platform

The platform for which wheels should be built

Possible values:

• windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
• linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
• macos: An alias for aarch64-apple-darwin, the default target for macOS
• x86_64-pc-windows-msvc: A 64-bit x86 Windows target
• aarch64-pc-windows-msvc: An ARM64 Windows target
• i686-pc-windows-msvc: A 32-bit x86 Windows target
• x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
• aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
• x86_64-apple-darwin: An x86 macOS target
• aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
• aarch64-unknown-linux-musl: An ARM64 Linux target
• x86_64-unknown-linux-musl: An x86_64 Linux target
• riscv64-unknown-linux: A RISCV64 Linux target
• x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
• x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
• x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
• x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
• x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
• x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
• x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
• x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
• x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
• x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
• x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
• x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
• x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
• aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
• aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
• aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
• aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
• aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
• aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
• aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
• aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
• aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
• aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
• aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
• aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
• aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
• aarch64-linux-android: An ARM64 Android target
• x86_64-linux-android: An x86_64 Android target
• wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
• arm64-apple-ios: An ARM64 target for iOS device
• arm64-apple-ios-simulator: An ARM64 target for iOS simulator
• x86_64-apple-ios-simulator: An x86_64 target for iOS simulator

--python-version python-version

The minimum Python version that should be supported by the built wheels (e.g., 3.7 or 3.7.9)

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--requirements, --requirement, -r requirements

Build wheels for the packages listed in the given files.

The following formats are supported: requirements.txt, .py files with inline metadata, pyproject.toml, setup.py, and setup.cfg.

If a pyproject.toml, setup.py, or setup.cfg file is provided, fyn will extract the requirements for the relevant project.

If - is provided, then requirements will be read from stdin.

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--system

Use a system Python interpreter during resolution

May also be set with the UV_SYSTEM_PYTHON environment variable.

--torch-backend torch-backend

The backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto)

May also be set with the UV_TORCH_BACKEND environment variable.

Possible values:

• auto: Select the appropriate PyTorch index based on the operating system and CUDA driver version
• cpu: Use the CPU-only PyTorch index
• cu130: Use the PyTorch index for CUDA 13.0
• cu129: Use the PyTorch index for CUDA 12.9
• cu128: Use the PyTorch index for CUDA 12.8
• cu126: Use the PyTorch index for CUDA 12.6
• cu125: Use the PyTorch index for CUDA 12.5
• cu124: Use the PyTorch index for CUDA 12.4
• cu123: Use the PyTorch index for CUDA 12.3
• cu122: Use the PyTorch index for CUDA 12.2
• cu121: Use the PyTorch index for CUDA 12.1
• cu120: Use the PyTorch index for CUDA 12.0
• cu118: Use the PyTorch index for CUDA 11.8
• cu117: Use the PyTorch index for CUDA 11.7
• cu116: Use the PyTorch index for CUDA 11.6
• cu115: Use the PyTorch index for CUDA 11.5
• cu114: Use the PyTorch index for CUDA 11.4
• cu113: Use the PyTorch index for CUDA 11.3
• cu112: Use the PyTorch index for CUDA 11.2
• cu111: Use the PyTorch index for CUDA 11.1
• cu110: Use the PyTorch index for CUDA 11.0
• cu102: Use the PyTorch index for CUDA 10.2
• cu101: Use the PyTorch index for CUDA 10.1
• cu100: Use the PyTorch index for CUDA 10.0
• cu92: Use the PyTorch index for CUDA 9.2
• cu91: Use the PyTorch index for CUDA 9.1
• cu90: Use the PyTorch index for CUDA 9.0
• cu80: Use the PyTorch index for CUDA 8.0
• rocm7.1: Use the PyTorch index for ROCm 7.1
• rocm7.0: Use the PyTorch index for ROCm 7.0
• rocm6.4: Use the PyTorch index for ROCm 6.4
• rocm6.3: Use the PyTorch index for ROCm 6.3
• rocm6.2.4: Use the PyTorch index for ROCm 6.2.4
• rocm6.2: Use the PyTorch index for ROCm 6.2
• rocm6.1: Use the PyTorch index for ROCm 6.1
• rocm6.0: Use the PyTorch index for ROCm 6.0
• rocm5.7: Use the PyTorch index for ROCm 5.7
• rocm5.6: Use the PyTorch index for ROCm 5.6
• rocm5.5: Use the PyTorch index for ROCm 5.5
• rocm5.4.2: Use the PyTorch index for ROCm 5.4.2
• rocm5.4: Use the PyTorch index for ROCm 5.4
• rocm5.3: Use the PyTorch index for ROCm 5.3
• rocm5.2: Use the PyTorch index for ROCm 5.2
• rocm5.1.1: Use the PyTorch index for ROCm 5.1.1
• rocm4.2: Use the PyTorch index for ROCm 4.2
• rocm4.1: Use the PyTorch index for ROCm 4.1
• rocm4.0.1: Use the PyTorch index for ROCm 4.0.1
• xpu: Use the PyTorch index for Intel XPU

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

--wheel-dir, -w wheel-dir

Store built wheels in the given directory.

Defaults to the current working directory.

fyn pip index

Inspect package indexes

Usage

fyn pip index [OPTIONS] <COMMAND>

Commands

fyn pip index versions

Show available versions for a package

fyn pip index versions

Show available versions for a package

Usage

fyn pip index versions [OPTIONS] <PACKAGE>

Arguments

PACKAGE

The package to inspect

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to use when filtering compatible versions.

By default, fyn uses the current Python interpreter and its platform tags.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--python-platform python-platform

The platform to use when filtering compatible versions.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

Possible values:

• windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
• linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
• macos: An alias for aarch64-apple-darwin, the default target for macOS
• x86_64-pc-windows-msvc: A 64-bit x86 Windows target
• aarch64-pc-windows-msvc: An ARM64 Windows target
• i686-pc-windows-msvc: A 32-bit x86 Windows target
• x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
• aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
• x86_64-apple-darwin: An x86 macOS target
• aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
• aarch64-unknown-linux-musl: An ARM64 Linux target
• x86_64-unknown-linux-musl: An x86_64 Linux target
• riscv64-unknown-linux: A RISCV64 Linux target
• x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
• x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
• x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
• x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
• x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
• x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
• x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
• x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
• x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
• x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
• x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
• x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
• x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
• aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
• aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
• aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
• aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
• aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
• aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
• aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
• aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
• aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
• aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
• aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
• aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
• aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
• aarch64-linux-android: An ARM64 Android target
• x86_64-linux-android: An x86_64 Android target
• wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
• arm64-apple-ios: An ARM64 target for iOS device
• arm64-apple-ios-simulator: An ARM64 target for iOS simulator
• x86_64-apple-ios-simulator: An x86_64 target for iOS simulator

--python-version python-version

The Python version to use when filtering compatible versions.

Defaults to the version of the discovered Python interpreter.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--system

Use the system Python environment when filtering compatible versions.

Disables discovery of virtual environments.

See fyn python for details on Python discovery.

May also be set with the UV_SYSTEM_PYTHON environment variable.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn pip upgrade

Upgrade packages in an environment

Usage

fyn pip upgrade [OPTIONS] --all

Options

--all

Upgrade all installed packages in the current environment

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--break-system-packages

Allow fyn to modify an EXTERNALLY-MANAGED Python installation.

WARNING: --break-system-packages is intended for use in continuous integration (CI) environments, when installing into Python installations that are managed by an external package manager, like apt. It should be used with caution, as such Python installations explicitly recommend against modifications by other package managers (like fyn or pip).

May also be set with the UV_BREAK_SYSTEM_PACKAGES environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--compile-bytecode, --compile

Compile Python files to bytecode after installation.

By default, fyn does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, fyn will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

May also be set with the UV_COMPILE_BYTECODE environment variable.

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--dry-run

Perform a dry run, i.e., don't actually install anything but resolve the dependencies and print the resulting plan

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

--no-break-system-packages

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Alias for --only-binary :all:.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--only-binary only-binary

Only use pre-built wheels; don't build source distributions.

When enabled, resolving will not run code from the given packages. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

--prefix prefix

Upgrade packages in lib, bin, and other top-level folders under the specified directory, as if a virtual environment were present at that location.

In general, prefer the use of --python to upgrade an alternate environment, as scripts and other artifacts installed via --prefix will reference the installing interpreter, rather than any interpreter added to the --prefix directory, rendering them non-portable.

Unlike other upgrade operations, this command does not require discovery of an existing Python environment and only searches for a Python interpreter to use for package resolution. If a suitable Python interpreter cannot be found, fyn will install one. To disable this, add --no-python-downloads.

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter into which packages should be upgraded.

By default, upgrading requires a virtual environment. A path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--python-platform python-platform

The platform for which requirements should be installed.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.

WARNING: When specified, fyn will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.

Possible values:

• windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
• linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
• macos: An alias for aarch64-apple-darwin, the default target for macOS
• x86_64-pc-windows-msvc: A 64-bit x86 Windows target
• aarch64-pc-windows-msvc: An ARM64 Windows target
• i686-pc-windows-msvc: A 32-bit x86 Windows target
• x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
• aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
• x86_64-apple-darwin: An x86 macOS target
• aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
• aarch64-unknown-linux-musl: An ARM64 Linux target
• x86_64-unknown-linux-musl: An x86_64 Linux target
• riscv64-unknown-linux: A RISCV64 Linux target
• x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
• x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
• x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
• x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
• x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
• x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
• x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
• x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
• x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
• x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
• x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
• x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
• x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
• aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
• aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
• aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
• aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
• aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
• aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
• aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
• aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
• aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
• aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
• aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
• aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
• aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
• aarch64-linux-android: An ARM64 Android target
• x86_64-linux-android: An x86_64 Android target
• wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
• arm64-apple-ios: An ARM64 target for iOS device
• arm64-apple-ios-simulator: An ARM64 target for iOS simulator
• x86_64-apple-ios-simulator: An x86_64 target for iOS simulator

--python-version python-version

The minimum Python version that should be supported by the requirements (e.g., 3.7 or 3.7.9).

If a patch version is omitted, the minimum patch version is assumed. For example, 3.7 is mapped to 3.7.0.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--reinstall, --force-reinstall

Reinstall all packages, regardless of whether they're already installed. Implies --refresh

--reinstall-package reinstall-package

Reinstall a specific package, regardless of whether it's already installed. Implies --refresh-package

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--strict

Validate the Python environment after completing the upgrade, to detect packages with missing dependencies or other issues

--system

Upgrade packages in the system Python environment.

By default, fyn upgrades packages in the virtual environment in the current working directory or any parent directory. The --system option instructs fyn to instead use the first Python found in the system PATH.

WARNING: --system is intended for use in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

May also be set with the UV_SYSTEM_PYTHON environment variable.

--target, -t target

Upgrade packages in the specified directory, rather than in the virtual or system Python environment. The packages will be installed at the top-level of the directory.

Unlike other upgrade operations, this command does not require discovery of an existing Python environment and only searches for a Python interpreter to use for package resolution. If a suitable Python interpreter cannot be found, fyn will install one. To disable this, add --no-python-downloads.

--torch-backend torch-backend

The backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto).

When set, fyn will ignore the configured index URLs for packages in the PyTorch ecosystem, and will instead use the defined backend.

For example, when set to cpu, fyn will use the CPU-only PyTorch index; when set to cu126, fyn will use the PyTorch index for CUDA 12.6.

The auto mode will attempt to detect the appropriate PyTorch index based on the currently installed CUDA drivers.

This option is in preview and may change in any future release.

May also be set with the UV_TORCH_BACKEND environment variable.

Possible values:

• auto: Select the appropriate PyTorch index based on the operating system and CUDA driver version
• cpu: Use the CPU-only PyTorch index
• cu130: Use the PyTorch index for CUDA 13.0
• cu129: Use the PyTorch index for CUDA 12.9
• cu128: Use the PyTorch index for CUDA 12.8
• cu126: Use the PyTorch index for CUDA 12.6
• cu125: Use the PyTorch index for CUDA 12.5
• cu124: Use the PyTorch index for CUDA 12.4
• cu123: Use the PyTorch index for CUDA 12.3
• cu122: Use the PyTorch index for CUDA 12.2
• cu121: Use the PyTorch index for CUDA 12.1
• cu120: Use the PyTorch index for CUDA 12.0
• cu118: Use the PyTorch index for CUDA 11.8
• cu117: Use the PyTorch index for CUDA 11.7
• cu116: Use the PyTorch index for CUDA 11.6
• cu115: Use the PyTorch index for CUDA 11.5
• cu114: Use the PyTorch index for CUDA 11.4
• cu113: Use the PyTorch index for CUDA 11.3
• cu112: Use the PyTorch index for CUDA 11.2
• cu111: Use the PyTorch index for CUDA 11.1
• cu110: Use the PyTorch index for CUDA 11.0
• cu102: Use the PyTorch index for CUDA 10.2
• cu101: Use the PyTorch index for CUDA 10.1
• cu100: Use the PyTorch index for CUDA 10.0
• cu92: Use the PyTorch index for CUDA 9.2
• cu91: Use the PyTorch index for CUDA 9.1
• cu90: Use the PyTorch index for CUDA 9.0
• cu80: Use the PyTorch index for CUDA 8.0
• rocm7.1: Use the PyTorch index for ROCm 7.1
• rocm7.0: Use the PyTorch index for ROCm 7.0
• rocm6.4: Use the PyTorch index for ROCm 6.4
• rocm6.3: Use the PyTorch index for ROCm 6.3
• rocm6.2.4: Use the PyTorch index for ROCm 6.2.4
• rocm6.2: Use the PyTorch index for ROCm 6.2
• rocm6.1: Use the PyTorch index for ROCm 6.1
• rocm6.0: Use the PyTorch index for ROCm 6.0
• rocm5.7: Use the PyTorch index for ROCm 5.7
• rocm5.6: Use the PyTorch index for ROCm 5.6
• rocm5.5: Use the PyTorch index for ROCm 5.5
• rocm5.4.2: Use the PyTorch index for ROCm 5.4.2
• rocm5.4: Use the PyTorch index for ROCm 5.4
• rocm5.3: Use the PyTorch index for ROCm 5.3
• rocm5.2: Use the PyTorch index for ROCm 5.2
• rocm5.1.1: Use the PyTorch index for ROCm 5.1.1
• rocm4.2: Use the PyTorch index for ROCm 4.2
• rocm4.1: Use the PyTorch index for ROCm 4.1
• rocm4.0.1: Use the PyTorch index for ROCm 4.0.1
• xpu: Use the PyTorch index for Intel XPU

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn pip uninstall

Uninstall packages from an environment

Usage

fyn pip uninstall [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>>

Arguments

PACKAGE

Uninstall all listed packages

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--break-system-packages

Allow fyn to modify an EXTERNALLY-MANAGED Python installation.

WARNING: --break-system-packages is intended for use in continuous integration (CI) environments, when installing into Python installations that are managed by an external package manager, like apt. It should be used with caution, as such Python installations explicitly recommend against modifications by other package managers (like fyn or pip).

May also be set with the UV_BREAK_SYSTEM_PACKAGES environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--dry-run

Perform a dry run, i.e., don't actually uninstall anything but print the resulting plan

--help, -h

Display the concise help for this command

--keyring-provider keyring-provider

Attempt to use keyring for authentication for remote requirements files.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-break-system-packages

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--prefix prefix

Uninstall packages from the specified --prefix directory

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter from which packages should be uninstalled.

By default, uninstallation requires a virtual environment. A path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--requirements, --requirement, -r requirements

Uninstall the packages listed in the given files.

The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.

--system

Use the system Python to uninstall packages.

By default, fyn uninstalls from the virtual environment in the current working directory or any parent directory. The --system option instructs fyn to instead use the first Python found in the system PATH.

WARNING: --system is intended for use in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

May also be set with the UV_SYSTEM_PYTHON environment variable.

--target, -t target

Uninstall packages from the specified --target directory

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn pip freeze

List, in requirements format, packages installed in an environment

Usage

fyn pip freeze [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--exclude exclude

Exclude the specified package(s) from the output

--exclude-editable

Exclude any editable packages from output

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--path paths

Restrict to the specified installation path for listing packages (can be used multiple times)

--prefix prefix

List packages from the specified --prefix directory

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter for which packages should be listed.

By default, fyn lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--strict

Validate the Python environment, to detect packages with missing dependencies and other issues

--system

List packages in the system Python environment.

Disables discovery of virtual environments.

See fyn python for details on Python discovery.

May also be set with the UV_SYSTEM_PYTHON environment variable.

--target, -t target

List packages from the specified --target directory

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn pip list

List, in tabular format, packages installed in an environment

Usage

fyn pip list [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--editable, -e

Only include editable projects

--exclude exclude

Exclude the specified package(s) from the output

--exclude-editable

Exclude any editable packages from output

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--format format

Select the output format

[default: columns]

Possible values:

• columns: Display the list of packages in a human-readable table
• freeze: Display the list of packages in a pip freeze-like format, with one package per line alongside its version
• json: Display the list of packages in a machine-readable JSON format

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--outdated

List outdated packages.

The latest version of each package will be shown alongside the installed version. Up-to-date packages will be omitted from the output.

--prefix prefix

List packages from the specified --prefix directory

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter for which packages should be listed.

By default, fyn lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--strict

Validate the Python environment, to detect packages with missing dependencies and other issues

--system

List packages in the system Python environment.

Disables discovery of virtual environments.

See fyn python for details on Python discovery.

May also be set with the UV_SYSTEM_PYTHON environment variable.

--target, -t target

List packages from the specified --target directory

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn pip show

Show information about one or more installed packages

Usage

fyn pip show [OPTIONS] [PACKAGE]...

Arguments

PACKAGE

The package(s) to display

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--files, -f

Show the full list of installed files for each package

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--prefix prefix

Show a package from the specified --prefix directory

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to find the package in.

By default, fyn looks for packages in a virtual environment but will look for packages in a system Python environment if no virtual environment is found.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--strict

Validate the Python environment, to detect packages with missing dependencies and other issues

--system

Show a package in the system Python environment.

Disables discovery of virtual environments.

See fyn python for details on Python discovery.

May also be set with the UV_SYSTEM_PYTHON environment variable.

--target, -t target

Show a package from the specified --target directory

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn pip tree

Display the dependency tree for an environment

Usage

fyn pip tree [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--depth, -d depth

Maximum display depth of the dependency tree

[default: 255]

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--invert, --reverse

Show the reverse dependencies for the given package. This flag will invert the tree and display the packages that depend on the given package

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-dedupe

Do not de-duplicate repeated dependencies. Usually, when a package has already displayed its dependencies, further occurrences will not re-display its dependencies, and will include a (*) to indicate it has already been shown. This flag will cause those duplicates to be repeated

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--outdated

Show the latest available version of each package in the tree

--package package

Display only the specified packages

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--prune prune

Prune the given package from the display of the dependency tree

--python, -p python

The Python interpreter for which packages should be listed.

By default, fyn lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--show-sizes

Show compressed wheel sizes for packages in the tree

--show-version-specifiers

Show the version constraint(s) imposed on each package

--strict

Validate the Python environment, to detect packages with missing dependencies and other issues

--system

List packages in the system Python environment.

Disables discovery of virtual environments.

See fyn python for details on Python discovery.

May also be set with the UV_SYSTEM_PYTHON environment variable.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn pip check

Verify installed packages have compatible dependencies

Usage

fyn pip check [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter for which packages should be checked.

By default, fyn checks packages in a virtual environment but will check packages in a system Python environment if no virtual environment is found.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--python-platform python-platform

The platform for which packages should be checked.

By default, the installed packages are checked against the platform of the current interpreter.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.

Possible values:

• windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
• linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
• macos: An alias for aarch64-apple-darwin, the default target for macOS
• x86_64-pc-windows-msvc: A 64-bit x86 Windows target
• aarch64-pc-windows-msvc: An ARM64 Windows target
• i686-pc-windows-msvc: A 32-bit x86 Windows target
• x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
• aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
• x86_64-apple-darwin: An x86 macOS target
• aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
• aarch64-unknown-linux-musl: An ARM64 Linux target
• x86_64-unknown-linux-musl: An x86_64 Linux target
• riscv64-unknown-linux: A RISCV64 Linux target
• x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
• x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
• x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
• x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
• x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
• x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
• x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
• x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
• x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
• x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
• x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
• x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
• x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
• aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
• aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
• aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
• aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
• aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
• aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
• aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
• aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
• aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
• aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
• aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
• aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
• aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
• aarch64-linux-android: An ARM64 Android target
• x86_64-linux-android: An x86_64 Android target
• wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
• arm64-apple-ios: An ARM64 target for iOS device
• arm64-apple-ios-simulator: An ARM64 target for iOS simulator
• x86_64-apple-ios-simulator: An x86_64 target for iOS simulator

--python-version python-version

The Python version against which packages should be checked.

By default, the installed packages are checked against the version of the current interpreter.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--system

Check packages in the system Python environment.

Disables discovery of virtual environments.

See fyn python for details on Python discovery.

May also be set with the UV_SYSTEM_PYTHON environment variable.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn torch

Diagnose PyTorch backend selection for the current machine

Usage

fyn torch [OPTIONS] <COMMAND>

Commands

fyn torch doctor

Inspect the current machine and recommend a PyTorch backend

fyn torch doctor

Inspect the current machine and recommend a PyTorch backend.

Detects the current accelerator, recommends the corresponding --torch-backend value, and prints the exact fyn pip install command to run next.

This command only reports information. It never installs packages or modifies project files.

Usage

fyn torch doctor [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--json

Display the diagnosis in JSON format

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn venv

Create a virtual environment.

By default, creates a virtual environment named .venv in the working directory. An alternative path may be provided positionally.

If in a project, the default environment name can be changed with the UV_PROJECT_ENVIRONMENT environment variable; this only applies when run from the project root directory.

If a virtual environment exists at the target path, it will be removed and a new, empty virtual environment will be created.

When using fyn, the virtual environment does not need to be activated. fyn will find a virtual environment (named .venv) in the working directory or any parent directories.

Usage

fyn venv [OPTIONS] [PATH]

Arguments

PATH

The path to the virtual environment to create.

Default to .venv in the working directory.

Relative paths are resolved relative to the working directory.

Options

--allow-existing

Preserve any existing files or directories at the target path.

By default, fyn venv will exit with an error if the given path is non-empty. The --allow-existing option will instead write to the given path, regardless of its contents, and without clearing it beforehand.

WARNING: This option can lead to unexpected behavior if the existing virtual environment and the newly-created virtual environment are linked to different Python interpreters.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--clear, -c

Remove any existing files or directories at the target path [env: UV_VENV_CLEAR=]

By default, fyn venv will exit with an error if the given path is non-empty. The --clear option will instead clear a non-empty path before creating a new virtual environment.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for a specific package to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or a ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

This option is only used for installing seed packages.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-project, --no-workspace

Avoid discovering a project or workspace.

By default, fyn searches for projects in the current directory or any parent directory to determine the default path of the virtual environment and check for Python version constraints, if any.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--prompt prompt

Provide an alternative prompt prefix for the virtual environment.

By default, the prompt is dependent on whether a path was provided to fyn venv. If provided (e.g, fyn venv project), the prompt is set to the directory name. If not provided (fyn venv), the prompt is set to the current directory's name.

If "." is provided, the current directory name will be used regardless of whether a path was provided to fyn venv.

--python, -p python

The Python interpreter to use for the virtual environment.

During virtual environment creation, fyn will not look for Python interpreters in virtual environments.

See fyn python for details on Python discovery and supported request formats.

May also be set with the UV_PYTHON environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--relocatable

Make the virtual environment relocatable [env: UV_VENV_RELOCATABLE=]

A relocatable virtual environment can be moved around and redistributed without invalidating its associated entrypoint and activation scripts.

Note that this can only be guaranteed for standard console_scripts and gui_scripts. Other scripts may be adjusted if they ship with a generic #!python[w] shebang, and binaries are left as-is.

As a result of making the environment relocatable (by way of writing relative, rather than absolute paths), the entrypoints and scripts themselves will not be relocatable. In other words, copying those entrypoints and scripts to a location outside the environment will not work, as they reference paths relative to the environment itself.

--seed

Install seed packages (one or more of: pip, setuptools, and wheel) into the virtual environment [env: UV_VENV_SEED=]

Note that setuptools and wheel are not included in Python 3.12+ environments.

--system-site-packages

Give the virtual environment access to the system site packages directory.

Unlike pip, when a virtual environment is created with --system-site-packages, fyn will not take system site packages into account when running commands like fyn pip list or fyn pip install. The --system-site-packages flag will provide the virtual environment with access to the system site packages directory at runtime, but will not affect the behavior of fyn commands.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn shell

Activate the virtual environment in a new shell.

Spawns a new shell process with the project's virtual environment activated. The virtual environment's bin directory is prepended to PATH and VIRTUAL_ENV is set.

Use exit or Ctrl-D to leave the activated shell.

Usage

fyn shell [OPTIONS] [PATH]

Arguments

PATH

The path to the virtual environment to activate.

If not provided, fyn will look for a .venv directory in the current directory or any parent directory. The VIRTUAL_ENV environment variable can also be used to specify the virtual environment.

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--env-file env-file

Load environment variables from a .env file.

Can be provided multiple times, with subsequent files overriding values defined in previous files.

May also be set with the UV_ENV_FILE environment variable.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-env-file

Avoid reading environment variables from a .env file [env: UV_NO_ENV_FILE=]

May also be set with the UV_NO_ENV_FILE environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-project, --no-workspace

Avoid discovering a project or workspace.

By default, fyn searches for projects in the current directory or any parent directory to determine the virtual environment path.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn build

Build Python packages into source distributions and wheels.

fyn build accepts a path to a directory or source distribution, which defaults to the current working directory.

By default, if passed a directory, fyn build will build a source distribution ("sdist") from the source directory, and a binary distribution ("wheel") from the source distribution.

fyn build --sdist can be used to build only the source distribution, fyn build --wheel can be used to build only the binary distribution, and fyn build --sdist --wheel can be used to build both distributions from source.

If passed a source distribution, fyn build --wheel will build a wheel from the source distribution.

Usage

fyn build [OPTIONS] [SRC]

Arguments

SRC

The directory from which distributions should be built, or a source distribution archive to build into a wheel.

Defaults to the current working directory.

Options

--all-packages, --all

Builds all packages in the workspace.

The workspace will be discovered from the provided source directory, or the current directory if no source directory is provided.

If the workspace member does not exist, fyn will exit with an error.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--build-constraints, --build-constraint, -b build-constraints

Constrain build dependencies using the given requirements files when building distributions.

Constraints files are requirements.txt-like files that only control the version of a build dependency that's installed. However, including a package in a constraints file will not trigger the inclusion of that package on its own.

May also be set with the UV_BUILD_CONSTRAINT environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--clear

Clear the output directory before the build, removing stale artifacts

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--default-index default-index

The URL of the default package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --index flag.

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--exclude-newer exclude-newer

Limit candidate packages to those that were uploaded prior to the given date.

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

May also be set with the UV_FIND_LINKS environment variable.

--force-pep517

Always build through PEP 517, don't use the fast path for the fyn build backend.

By default, fyn won't create a PEP 517 build environment for packages using the fyn build backend, but use a fast path that calls into the build backend directly. This option forces always using PEP 517.

--fork-strategy fork-strategy

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, fyn will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, fyn will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

• fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
• requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

By default, fyn will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

• first-index: Only use results from the first index that returns a match for a given package name
• unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
• unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

--index-url, -i index-url

(Deprecated: use --default-index instead) The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

May also be set with the UV_INDEX_URL environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The method to use when installing packages from the global cache.

This option is only used when building source distributions.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (fyn cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

May also be set with the UV_LINK_MODE environment variable.

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the source into the destination
• copy: Copy packages from the source into the destination
• hardlink: Hard link packages from the source into the destination
• symlink: Symbolically link packages from the source into the destination

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-binary

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

May also be set with the UV_NO_BINARY environment variable.

--no-binary-package no-binary-package

Don't install pre-built wheels for a specific package

May also be set with the UV_NO_BINARY_PACKAGE environment variable.

--no-build

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

May also be set with the UV_NO_BUILD environment variable.

--no-build-isolation

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

--no-build-isolation-package no-build-isolation-package

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

--no-build-logs

Hide logs from the build backend

--no-build-package no-build-package

Don't build source distributions for a specific package

May also be set with the UV_NO_BUILD_PACKAGE environment variable.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-create-gitignore

Do not create a .gitignore file in the output directory.

By default, fyn creates a .gitignore file in the output directory to exclude build artifacts from version control. When this flag is used, the file will be omitted.

--no-index

Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

Ignore the tool.fyn.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources

May also be set with the UV_NO_SOURCES environment variable.

--no-sources-package no-sources-package

Don't use sources from the tool.fyn.sources table for the specified packages

May also be set with the UV_NO_SOURCES_PACKAGE environment variable.

--no-verify-hashes

Disable validation of hashes in the requirements file.

By default, fyn will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash. To enforce hash validation, use --require-hashes.

May also be set with the UV_NO_VERIFY_HASHES environment variable.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--out-dir, -o out-dir

The output directory to which distributions should be written.

Defaults to the dist subdirectory within the source directory, or the directory containing the source distribution archive.

--package package

Build a specific package in the workspace.

The workspace will be discovered from the provided source directory, or the current directory if no source directory is provided.

If the workspace member does not exist, fyn will exit with an error.

--prerelease prerelease

The strategy to use when considering pre-release versions.

By default, fyn will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

May also be set with the UV_PRERELEASE environment variable.

Possible values:

• disallow: Disallow all pre-release versions
• allow: Allow all pre-release versions
• if-necessary: Allow pre-release versions if all versions of a package are pre-release
• explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
• if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--python, -p python

The Python interpreter to use for the build environment.

By default, builds are executed in isolated virtual environments. The discovered interpreter will be used to create those environments, and will be symlinked or copied in depending on the platform.

See fyn python to view supported request formats.

May also be set with the UV_PYTHON environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--require-hashes

Require a matching hash for each requirement.

By default, fyn will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash.

When --require-hashes is enabled, all requirements must include a hash or set of hashes, and all requirements must either be pinned to exact versions (e.g., ==1.0.0), or be specified via direct URL.

Hash-checking mode introduces a number of additional constraints:

• Git dependencies are not supported. - Editable installations are not supported. - Local dependencies are not supported, unless they point to a specific wheel (.whl) or source archive (.zip, .tar.gz), as opposed to a directory.

May also be set with the UV_REQUIRE_HASHES environment variable.

--resolution resolution

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, fyn will use the latest compatible version of each package (highest).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

• highest: Resolve the highest compatible version of each package
• lowest: Resolve the lowest compatible version of each package
• lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

--sdist

Build a source distribution ("sdist") from the given directory

--upgrade, -U

Allow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh

--upgrade-package, -P upgrade-package

Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

--wheel

Build a binary distribution ("wheel") from the given directory

fyn publish

Upload distributions to an index

Usage

fyn publish [OPTIONS] [FILES]...

Arguments

FILES

Paths to the files to upload. Accepts glob expressions.

Defaults to the dist directory. Selects only wheels and source distributions and their attestations, while ignoring other files.

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--check-url check-url

Check an index URL for existing files to skip duplicate uploads.

This option allows retrying publishing that failed after only some, but not all files have been uploaded, and handles errors due to parallel uploads of the same file.

Before uploading, the index is checked. If the exact same file already exists in the index, the file will not be uploaded. If an error occurred during the upload, the index is checked again, to handle cases where the identical file was uploaded twice in parallel.

The exact behavior will vary based on the index. When uploading to PyPI, uploading the same file succeeds even without --check-url, while most other indexes error. When uploading to pyx, the index URL can be inferred automatically from the publish URL.

The index must provide one of the supported hashes (SHA-256, SHA-384, or SHA-512).

May also be set with the UV_PUBLISH_CHECK_URL environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--dry-run

Perform a dry run without uploading files.

When enabled, the command will check for existing files if --check-url is provided, and will perform validation against the index if supported, but will not upload any files.

--help, -h

Display the concise help for this command

--index index

The name of an index in the configuration to use for publishing.

The index must have a publish-url setting, for example:

[[tool.fyn.index]]
name = "pypi"
url = "https://pypi.org/simple"
publish-url = "https://upload.pypi.org/legacy/"

The index url will be used to check for existing files to skip duplicate uploads.

With these settings, the following two calls are equivalent:

fyn publish --index pypi
fyn publish --publish-url https://upload.pypi.org/legacy/ --check-url https://pypi.org/simple

May also be set with the UV_PUBLISH_INDEX environment variable.

--keyring-provider keyring-provider

Attempt to use keyring for authentication for remote requirements files.

At present, only --keyring-provider subprocess is supported, which configures fyn to use the keyring CLI to handle authentication.

Defaults to disabled.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

• disabled: Do not use keyring for credential lookup
• subprocess: Use the keyring command for credential lookup

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-attestations

Do not upload attestations for the published files.

By default, fyn attempts to upload matching PEP 740 attestations with each distribution that is published.

May also be set with the UV_PUBLISH_NO_ATTESTATIONS environment variable.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--password, -p password

The password for the upload

May also be set with the UV_PUBLISH_PASSWORD environment variable.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--publish-url publish-url

The URL of the upload endpoint (not the index URL).

Note that there are typically different URLs for index access (e.g., https:://.../simple) and index upload.

Defaults to PyPI's publish URL (https://upload.pypi.org/legacy/).

May also be set with the UV_PUBLISH_URL environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--token, -t token

The token for the upload.

Using a token is equivalent to passing __token__ as --username and the token as --password password.

May also be set with the UV_PUBLISH_TOKEN environment variable.

--trusted-publishing trusted-publishing

Configure trusted publishing.

By default, fyn checks for trusted publishing when running in a supported environment, but ignores it if it isn't configured.

fyn's supported environments for trusted publishing include GitHub Actions and GitLab CI/CD.

Possible values:

• automatic: Attempt trusted publishing when we're in a supported environment, continue if that fails
• always
• never

--username, -u username

The username for the upload

May also be set with the UV_PUBLISH_USERNAME environment variable.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn cache

Manage fyn's cache

Usage

fyn cache [OPTIONS] <COMMAND>

Commands

fyn cache clean

Clear the cache, removing all entries or those linked to specific packages

fyn cache prune

Prune all unreachable objects from the cache

fyn cache dir

Show the cache directory

fyn cache size

Show the cache size

fyn cache clean

Clear the cache, removing all entries or those linked to specific packages

Usage

fyn cache clean [OPTIONS] [PACKAGE]...

Arguments

PACKAGE

The packages to remove from the cache

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--force

Force removal of the cache, ignoring in-use checks.

By default, fyn cache clean will block until no process is reading the cache. When --force is used, fyn cache clean will proceed without taking a lock.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn cache prune

Prune all unreachable objects from the cache

Usage

fyn cache prune [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--ci

Optimize the cache for persistence in a continuous integration environment, like GitHub Actions.

By default, fyn caches both the wheels that it builds from source and the pre-built wheels that it downloads directly, to enable high-performance package installation. In some scenarios, though, persisting pre-built wheels may be undesirable. For example, in GitHub Actions, it's faster to omit pre-built wheels from the cache and instead have re-download them on each run. However, it typically is faster to cache wheels that are built from source, since the wheel building process can be expensive, especially for extension modules.

In --ci mode, fyn will prune any pre-built wheels from the cache, but retain any wheels that were built from source.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--force

Force removal of the cache, ignoring in-use checks.

By default, fyn cache prune will block until no process is reading the cache. When --force is used, fyn cache prune will proceed without taking a lock.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn cache dir

Show the cache directory.

By default, the cache is stored in $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on Unix and %LOCALAPPDATA%\fyn\cache on Windows.

When --no-cache is used, the cache is stored in a temporary directory and discarded when the process exits.

An alternative cache directory may be specified via the cache-dir setting, the --cache-dir option, or the $UV_CACHE_DIR environment variable.

Note that it is important for performance for the cache directory to be located on the same file system as the Python environment fyn is operating on.

Usage

fyn cache dir [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn cache size

Show the cache size.

Displays the total size of the cache directory. This includes all downloaded and built wheels, source distributions, and other cached data. By default, outputs the size in raw bytes; use --human for human-readable output.

Usage

fyn cache size [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--human, --human-readable, -H

Display the cache size in human-readable format (e.g., 1.2 GiB instead of raw bytes)

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn status

Show the current project and environment status

Usage

fyn status [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--check

Fail if obvious project status checks do not pass

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--json

Display the status in JSON format

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn self

Manage the fyn executable

Usage

fyn self [OPTIONS] <COMMAND>

Commands

fyn self update

Update fyn

fyn self version

Display fyn's version

fyn self update

Update fyn

Usage

fyn self update [OPTIONS] [TARGET_VERSION]

Arguments

TARGET_VERSION

Update to the specified version. If not provided, fyn will update to the latest version

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--dry-run

Run without performing the update

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--token token

A GitHub token for authentication. A token is not required but can be used to reduce the chance of encountering rate limits

May also be set with the UV_GITHUB_TOKEN environment variable.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn self version

Display fyn's version

Usage

fyn self version [OPTIONS]

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--output-format output-format

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--short

Only print the version

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

fyn generate-shell-completion

Generate shell completion

Usage

fyn generate-shell-completion [OPTIONS] <SHELL>

Arguments

SHELL

The shell to generate the completion script for

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

fyn help

Display documentation for a command

Usage

fyn help [OPTIONS] [COMMAND]...

Arguments

COMMAND

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/fyn or $HOME/.cache/fyn on macOS and Linux, and %LOCALAPPDATA%\fyn\cache on Windows.

To view the location of the cache directory, run fyn cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, fyn will automatically detect support for colors when writing to a terminal.

Possible values:

• auto: Enables colored output only when the output is going to a terminal or TTY with support
• always: Enables colored output regardless of the detected environment
• never: Disables colored output

--config-file config-file

The path to a fyn.toml file to use for configuration.

While fyn configuration can be included in a pyproject.toml file, it is not allowed in this context.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--managed-python

Require use of fyn-managed Python versions [env: UV_MANAGED_PYTHON=]

By default, fyn prefers using Python versions it manages. However, it will use system Python versions if a fyn-managed Python is not installed. This option disables use of system Python versions.

--native-tls, --system-certs

Whether to load TLS certificates from the platform's native store [env: UV_NATIVE_TLS=]

By default, fyn loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in fyn improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

--no-cache, --no-cache-dir, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

May also be set with the UV_NO_CACHE environment variable.

--no-config

Avoid discovering configuration files (pyproject.toml, fyn.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of fyn-managed Python versions [env: UV_NO_MANAGED_PYTHON=]

Instead, fyn will search for a suitable Python version on the system.

--no-pager

Disable pager when printing help

--no-progress

Hide all progress outputs [env: UV_NO_PROGRESS=]

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access [env: UV_OFFLINE=]

When disabled, fyn will only use locally cached data and locally available files.

--project project

Discover a project in the given directory.

All pyproject.toml, fyn.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the fyn pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which fyn will write no output to stdout.

--verbose, -v

Use verbose output.

You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)