otty / apps

All apps/uv

uv

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

Runs as uv, uvx|macOS, Linux, Windows|docs.astral.sh

Open form in Otty otty.toml

Sync rules

What travels, what stays, what never leaves

uv in your home directory Every rule on this page, by file

cache-dir

Each machine keeps its own copy of these.

· ~/.cache/uv/ Exclude

· python/ Exclude

· tools/ Exclude

· credentials/credentials.toml Never synced

Only what the catalog names. A directory that syncs brings everything inside it except what is listed as excluded here.

apps/uv/otty.tomlThe file this page is generated from

id = "uv"

name = "uv"

homepage = "https://docs.astral.sh/uv/"

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

icon = "SimpleIcons:uv"

executables = ["uv", "uvx"]

[dotfiles]

# https://docs.astral.sh/uv/concepts/configuration-files/ — "uv will also

# discover uv.toml configuration files in the user- and system-level

# configuration directories, e.g., user-level configuration in

# ~/.config/uv/uv.toml on macOS and Linux, or %APPDATA%\uv\uv.toml on

# Windows." That is `[configHome]` — the XDG configuration directory on macOS

# as well as Linux, so $XDG_CONFIG_HOME moves it and one entry covers Windows

# too. The /etc/uv/uv.toml and %PROGRAMDATA% copies are system-level and out

# of scope; pyproject.toml belongs to the project.

paths = ["[configHome]/uv/uv.toml"]

# https://docs.astral.sh/uv/reference/storage/ gives the cache directory as

# $XDG_CACHE_HOME or $HOME/.cache/uv on macOS and Linux and

# %LOCALAPPDATA%\uv\cache on Windows, and the persistent data directory —

# installed Python versions and `uv tool` environments — as

# $XDG_DATA_HOME or $HOME/.local/share/uv, %APPDATA%\uv\data on Windows. All

# of it is rebuildable machine state. The Unix spellings are `[xdgCache]` and

# `[xdgData]`, the XDG halves of those pairs, and uv reads the variables rather

# than assuming their defaults: crates/uv-dirs/src/lib.rs resolves both through

# `etcetera::base_strategy::choose_base_strategy()`, which is the XDG strategy

# on macOS as well as Linux and looks up $XDG_CACHE_HOME and $XDG_DATA_HOME

# before falling back. `uv cache dir`, `uv python dir` and `uv tool dir` print

# the resolved paths and follow those variables when they are set. (The

# `legacy_*` functions beside them take the native strategy — ~/Library/Caches

# and ~/Library/Application Support — but those are the pre-migration

# directories uv only reads, not ones it fills.) The Windows copies stay

# written out: they sit under \uv\cache and \uv\data rather than at the root of

# the base directory, so no placeholder reaches them.

exclude = [

"[xdgCache]/uv/",

"%LOCALAPPDATA%/uv/cache/",

"[xdgData]/uv/python/",

"[xdgData]/uv/tools/",

]

# https://docs.astral.sh/uv/concepts/authentication/http/, "The uv credentials

# store": "Credentials are stored in a plaintext file in uv's state directory,

# e.g., ~/.local/share/uv/credentials/credentials.toml on Unix." That is the

# data directory above, so it is written as `[xdgData]` for the same reason.

# The Windows spelling is the same relative path under the documented Windows

# data directory (%APPDATA%\uv\data); it is listed so the file is withheld

# there too, since marking one file too many costs nothing and missing one

# leaks a token. ~/.netrc, which uv also reads, belongs to curl's entry.

secret = [

"[xdgData]/uv/credentials/credentials.toml",

"%APPDATA%/uv/data/credentials/credentials.toml",

]

# Read at the start of a uv invocation; nothing holds it open.

side_effect = false

# cache-dir names a directory on this machine's disk — a different volume, a

# different drive letter, a scratch partition that only exists here — so the

# line does not travel, while index-url, python-preference and resolution

# settings do. The file is one base-directory path on every platform, so the

# rule has a single spelling to name.

# The volume is one the user picked, so the line is kept for rebuilding this

# machine rather than dropped, and is applied to no other.

[[dotfiles.machine_lines]]

file = "[configHome]/uv/uv.toml"

match = { key_path = ["cache-dir"] }

scope = "backup"

# No secret_paths inside uv.toml. An index URL can carry an embedded token,

# but the overwhelming majority are public, and `uv auth login` writes to the

# credentials store above rather than into this file — the consumer's own

# content scan is the right layer for the rare inline one.

[commands]

format = 1

label = "uv"

description = "Python project and package manager. Forms cover add, run, sync and venv; global flags and index/resolution tuning are left out."

quality = "ai-draft"

base = "fig:uv"

parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = true }

[[commands.source]]

id = "fig"

kind = "completion"

url = "https://github.com/withfig/autocomplete/blob/master/src/uv.ts"

license = "MIT"

[[commands.subcommand]]

path = ["add"]

label = "Add dependencies"

description = "Add packages to the project in the current directory. Index, resolution and build options are left out."

[[commands.subcommand.source]]

id = "fig"

kind = "completion"

url = "https://github.com/withfig/autocomplete/blob/master/src/uv.ts"

license = "MIT"

[[commands.subcommand.field]]

id = "packages"

label = "Packages"

description = "Package specifiers, e.g. requests or \"flask>=3\"."

type = "string"

position = 0

multiple = true

min = 1

sources = ["fig"]

[[commands.subcommand.field]]

id = "dev"

label = "Development dependency"

type = "boolean"

option = ["--dev"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "group"

label = "Dependency group"

type = "string"

option = ["--group"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "optional"

label = "Optional extra"

description = "Add to the named optional-dependencies extra."

type = "string"

option = ["--optional"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "editable"

label = "Editable"

type = "boolean"

option = ["--editable"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "extra"

label = "Enable extra"

type = "string"

option = ["--extra"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "rev"

label = "Git revision"

type = "string"

option = ["--rev"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "tag"

label = "Git tag"

type = "string"

option = ["--tag"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "branch"

label = "Git branch"

type = "string"

option = ["--branch"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "package"

label = "Workspace package"

type = "string"

option = ["--package"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "upgrade"

label = "Allow upgrades"

type = "boolean"

option = ["-U"]

sources = ["fig"]

[[commands.subcommand.task]]

id = "add"

label = "Add packages"

fields = ["packages"]

required = ["packages"]

[[commands.subcommand.task]]

id = "add-dev"

label = "Add dev dependency"

set = { dev = [true] }

fields = ["packages", "dev"]

required = ["packages"]

[[commands.subcommand.group]]

id = "basic"

label = "Basic"

fields = ["packages", "dev", "group", "optional", "editable"]

[[commands.subcommand.group]]

id = "advanced"

label = "Advanced"

fields = ["rev", "tag", "branch", "package", "upgrade", "extra"]

[[commands.subcommand]]

path = ["run"]

label = "Run a command"

description = "Run a command or script in the project environment. Arguments for the command itself are typed after it."

[[commands.subcommand.source]]

id = "fig"

kind = "completion"

url = "https://github.com/withfig/autocomplete/blob/master/src/uv.ts"

license = "MIT"

[[commands.subcommand.field]]

id = "command"

label = "Command"

description = "Command or script to run."

type = "string"

position = 0

min = 1

sources = ["fig"]

[[commands.subcommand.field]]

id = "with"

label = "Extra package"

description = "Run with this package installed."

type = "string"

option = ["--with"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "module"

label = "Run as module"

type = "boolean"

option = ["-m", "--module"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "script"

label = "Treat as script"

type = "boolean"

option = ["-s", "--script"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "isolated"

label = "Isolated environment"

type = "boolean"

option = ["--isolated"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "no_sync"

label = "Skip sync"

type = "boolean"

option = ["--no-sync"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "locked"

label = "Assert lockfile unchanged"

type = "boolean"

option = ["--locked"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "frozen"

label = "Do not update lockfile"

type = "boolean"

option = ["--frozen"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "no_dev"

label = "Omit dev group"

type = "boolean"

option = ["--no-dev"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "all_extras"

label = "All extras"

type = "boolean"

option = ["--all-extras"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "extra"

label = "Extra"

type = "string"

option = ["--extra"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "group"

label = "Group"

type = "string"

option = ["--group"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "env_file"

label = "Env file"

type = "path"

option = ["--env-file"]

path = { kind = "file", role = "input" }

sources = ["fig"]

[[commands.subcommand.field]]

id = "package"

label = "Workspace package"

type = "string"

option = ["--package"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "no_project"

label = "No project"

type = "boolean"

option = ["--no-project"]

sources = ["fig"]

[[commands.subcommand.task]]

id = "run"

label = "Run command"

fields = ["command"]

required = ["command"]

[[commands.subcommand.task]]

id = "run-with"

label = "Run with extra package"

fields = ["command", "with"]

required = ["command", "with"]

[[commands.subcommand.group]]

id = "basic"

label = "Basic"

fields = ["command", "with", "module", "script", "isolated"]

[[commands.subcommand.group]]

id = "advanced"

label = "Advanced"

fields = ["no_sync", "locked", "frozen", "no_dev", "all_extras", "extra", "group", "env_file", "package", "no_project"]

[[commands.subcommand]]

path = ["sync"]

label = "Sync environment"

description = "Update the project's environment from the lockfile."

[[commands.subcommand.source]]

id = "fig"

kind = "completion"

url = "https://github.com/withfig/autocomplete/blob/master/src/uv.ts"

license = "MIT"

[[commands.subcommand.field]]

id = "all_extras"

label = "All extras"

type = "boolean"

option = ["--all-extras"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "extra"

label = "Extra"

type = "string"

option = ["--extra"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "no_dev"

label = "Omit dev group"

type = "boolean"

option = ["--no-dev"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "only_dev"

label = "Only dev group"

type = "boolean"

option = ["--only-dev"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "group"

label = "Group"

type = "string"

option = ["--group"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "all_groups"

label = "All groups"

type = "boolean"

option = ["--all-groups"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "inexact"

label = "Keep extraneous packages"

type = "boolean"

option = ["--inexact"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "no_install_project"

label = "Skip current project"

type = "boolean"

option = ["--no-install-project"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "all_packages"

label = "All workspace packages"

type = "boolean"

option = ["--all-packages"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "package"

label = "Workspace package"

type = "string"

option = ["--package"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "upgrade"

label = "Allow upgrades"

type = "boolean"

option = ["-U"]

sources = ["fig"]

[[commands.subcommand.task]]

id = "sync"

label = "Sync"

fields = ["no_dev", "all_extras"]

required = []

[[commands.subcommand.task]]

id = "sync-upgrade"

label = "Sync and upgrade"

set = { upgrade = [true] }

fields = ["upgrade"]

required = []

[[commands.subcommand.group]]

id = "basic"

label = "Basic"

fields = ["all_extras", "extra", "no_dev", "only_dev", "group", "all_groups"]

[[commands.subcommand.group]]

id = "advanced"

label = "Advanced"

fields = ["inexact", "no_install_project", "all_packages", "package", "upgrade"]

[[commands.subcommand]]

path = ["venv"]

label = "Create virtual environment"

description = "Create a virtual environment; the target path is the last argument."

[[commands.subcommand.source]]

id = "fig"

kind = "completion"

url = "https://github.com/withfig/autocomplete/blob/master/src/uv.ts"

license = "MIT"

[[commands.subcommand.field]]

id = "venv_path"

label = "Path"

type = "path"

position = 0

path = { kind = "directory", role = "output" }

sources = ["fig"]

[[commands.subcommand.field]]

id = "python"

label = "Python"

description = "Interpreter or version, e.g. 3.12."

type = "string"

option = ["-p", "--python"]

suggestions = [{ value = "3.13", label = "3.13" }, { value = "3.12", label = "3.12" }, { value = "3.11", label = "3.11" }]

sources = ["fig"]

[[commands.subcommand.field]]

id = "seed"

label = "Seed pip"

type = "boolean"

option = ["--seed"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "system_site"

label = "System site packages"

type = "boolean"

option = ["--system-site-packages"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "allow_existing"

label = "Allow existing"

type = "boolean"

option = ["--allow-existing"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "prompt"

label = "Prompt"

type = "string"

option = ["--prompt"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "relocatable"

label = "Relocatable"

type = "boolean"

option = ["--relocatable"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "no_project"

label = "No project"

type = "boolean"

option = ["--no-project"]

sources = ["fig"]

[[commands.subcommand.task]]

id = "venv"

label = "Create .venv"

fields = ["venv_path", "python"]

required = []

[[commands.subcommand.task]]

id = "venv-seed"

label = "Create with pip"

set = { seed = [true] }

fields = ["venv_path", "python", "seed"]

required = []

[[commands.subcommand.group]]

id = "basic"

label = "Basic"

fields = ["venv_path", "python", "seed"]

[[commands.subcommand.group]]

id = "advanced"

label = "Advanced"

fields = ["system_site", "allow_existing", "prompt", "relocatable", "no_project"]

Use it with your dotfile manager

Same data, in the shape your tool already reads

Opens Otty and adds this tool to what it syncs

Opens otty://sync/add/uv. Otty ships with this catalog, so the link only has to name the tool — nothing is downloaded.

Every one of these keeps all credential files out. None of them splits cache-dir for you — that part is Otty’s own sync, or a template you write by hand.