Initial commit

skills/uv/references/cli_reference.md

@@ -0,0 +1,632 @@
+# uv CLI Reference
+
+Complete command-line interface reference for uv (v0.9.5).
+
+## Global Flags
+
+Available across all commands:
+
+```bash
+--help, -h              Display help
+--verbose, -v           Verbose logging (repeat for more: -vv, -vvv)
+--quiet, -q             Suppress output
+--color <WHEN>          Color output (auto/always/never)
+--no-progress           Hide progress indicators
+--cache-dir <DIR>       Cache directory
+--no-cache              Disable caching
+--offline               Disable network access
+--python <VERSION>      Python interpreter/version
+--directory <PATH>      Working directory
+--config-file <PATH>    Custom config file
+--no-config             Ignore config files
+--preview               Enable preview features
+```
+
+## Project Commands
+
+### uv init
+
+Create new project or script.
+
+```bash
+uv init [OPTIONS] [PATH]
+
+--lib, --library        Create library (implies --package)
+--app, --application    Create application (default)
+--script                Create PEP 723 script
+--package               Distributable package with src/
+--no-package            Non-package (virtual) project
+--bare                  Minimal configuration only
+--build-backend <BACKEND>  Build system (hatchling/setuptools/uv_build)
+--python <VERSION>      Python version requirement
+--vcs <VCS>             Version control (git/none)
+--python-pin            Create .python-version
+```
+
+### uv add
+
+Add dependencies to project.
+
+```bash
+uv add [OPTIONS] <PACKAGES>...
+
+--dev                   Add to dev dependencies
+--group <GROUP>         Add to dependency group
+--optional <EXTRA>      Add to optional dependencies
+--editable, -e          Editable/development mode
+--frozen                Skip lockfile updates
+--locked                Assert lockfile unchanged
+--no-sync               Skip environment sync
+--bounds <TYPE>         Version constraint (lowest/compatible/exact)
+--branch <BRANCH>       Git branch
+--tag <TAG>             Git tag
+--rev <REV>             Git revision
+--raw-sources           Raw source specifiers
+```
+
+### uv remove
+
+Remove dependencies.
+
+```bash
+uv remove [OPTIONS] <PACKAGES>...
+
+--dev                   Remove from dev dependencies
+--group <GROUP>         Remove from dependency group
+--optional <EXTRA>      Remove from optional dependencies
+--frozen                Skip lockfile updates
+--locked                Assert lockfile unchanged
+```
+
+### uv sync
+
+Synchronize project environment with lockfile.
+
+```bash
+uv sync [OPTIONS]
+
+--extra <EXTRA>, -E     Include optional dependencies
+--all-extras            Include all optional dependencies
+--no-dev                Exclude dev dependencies
+--only-dev              Only dev dependencies
+--group <GROUP>         Include dependency group
+--only-group <GROUP>    Only specified group
+--no-install-project    Skip installing project itself
+--frozen                Use existing lockfile
+--locked                Assert lockfile unchanged
+--inexact               Allow non-exact versions
+--python <VERSION>      Target Python version
+```
+
+### uv lock
+
+Update project lockfile.
+
+```bash
+uv lock [OPTIONS]
+
+--frozen                Don't update lockfile
+--locked                Assert lockfile unchanged
+--upgrade, -U           Allow package upgrades
+--upgrade-package <PKG>, -P  Upgrade specific packages
+--dry-run               Show changes without writing
+```
+
+### uv run
+
+Execute commands in project environment.
+
+```bash
+uv run [OPTIONS] <COMMAND> [ARGS]...
+
+--python <VERSION>      Python version
+--module, -m            Run as module
+--script, -s            Treat as PEP 723 script
+--with <PKG>, -w        Include temporary packages
+--isolated              Fresh isolated environment
+--frozen                Skip lockfile updates
+--locked                Assert lockfile unchanged
+--no-sync               Skip environment sync
+--no-project            Don't load project environment
+--no-dev                Exclude dev dependencies
+--extra <EXTRA>         Include optional dependencies
+--all-extras            Include all optional dependencies
+--package <PKG>         Run for specific workspace package
+--env-file <FILE>       Load environment variables
+```
+
+### uv tree
+
+Display dependency tree.
+
+```bash
+uv tree [OPTIONS]
+
+--depth <DEPTH>         Maximum display depth
+--prune <PKG>           Prune packages from tree
+--package <PKG>         Show tree for specific package
+--invert                Show reverse dependencies
+--no-dedupe             Show all occurrences
+```
+
+### uv export
+
+Export dependencies to various formats.
+
+```bash
+uv export [OPTIONS]
+
+--format <FORMAT>       Output format (requirements-txt/pylock)
+-o, --output-file <FILE>  Output file path
+--extra <EXTRA>         Include optional dependencies
+--all-extras            Include all optional dependencies
+--no-dev                Exclude dev dependencies
+--frozen                Use existing lockfile
+```
+
+## Tool Management
+
+### uv tool run (alias: uvx)
+
+Execute tool without persistent installation.
+
+```bash
+uvx [OPTIONS] <COMMAND> [ARGS]...
+uv tool run [OPTIONS] <COMMAND> [ARGS]...
+
+--from <PACKAGE>        Source package
+--with <PACKAGE>        Include additional packages
+--python <VERSION>      Python version
+--isolated              Fresh environment
+```
+
+### uv tool install
+
+Install tool persistently.
+
+```bash
+uv tool install [OPTIONS] <PACKAGE>
+
+--from <PACKAGE>        Install from specific package
+--with <PACKAGE>        Include additional packages
+--python <VERSION>      Python version
+--force                 Overwrite existing
+--editable, -e          Editable mode
+```
+
+### uv tool upgrade
+
+Update installed tool.
+
+```bash
+uv tool upgrade [OPTIONS] [PACKAGE]
+
+--all                   Upgrade all tools
+```
+
+### uv tool list
+
+List installed tools.
+
+```bash
+uv tool list [OPTIONS]
+
+--show-paths            Display installation paths
+```
+
+### uv tool uninstall
+
+Remove installed tool.
+
+```bash
+uv tool uninstall <PACKAGE>
+```
+
+## Python Management
+
+### uv python install
+
+Install Python versions.
+
+```bash
+uv python install [OPTIONS] <VERSIONS>...
+
+--force                 Reinstall if present
+--preview               Allow preview versions
+```
+
+### uv python list
+
+List Python versions.
+
+```bash
+uv python list [OPTIONS]
+
+--all-versions          Show all available versions
+--only-installed        Show only installed versions
+```
+
+### uv python pin
+
+Pin Python version for project.
+
+```bash
+uv python pin [OPTIONS] <VERSION>
+
+--global                Pin globally for user
+--rm                    Remove pin
+--python-preference <PREF>  Preference (only-managed/managed/system/only-system)
+```
+
+### uv python find
+
+Locate Python interpreter.
+
+```bash
+uv python find <VERSION>
+```
+
+### uv python upgrade
+
+Update Python installations.
+
+```bash
+uv python upgrade [OPTIONS] [VERSION]
+
+--all                   Upgrade all installations
+```
+
+## pip Interface
+
+### uv pip install
+
+Install packages.
+
+```bash
+uv pip install [OPTIONS] <PACKAGES>...
+
+--requirement <FILE>, -r     Install from requirements
+--editable <PATH>, -e        Editable mode
+--constraint <FILE>, -c      Apply constraints
+--override <FILE>            Apply overrides
+--extra <EXTRA>              Install optional dependencies
+--all-extras                 Install all optional dependencies
+--no-deps                    Don't install dependencies
+--python <PYTHON>            Target Python environment
+--system                     Install into system Python
+--break-system-packages      Allow system modifications
+--target <DIR>               Install to directory
+--upgrade, -U                Upgrade packages
+--upgrade-package <PKG>, -P  Upgrade specific packages
+--force-reinstall            Reinstall even if satisfied
+--no-build                   Don't build from source
+--no-binary <PKG>            Don't use wheels
+--only-binary <PKG>          Only use wheels
+--dry-run                    Show changes without installing
+```
+
+### uv pip compile
+
+Generate requirements file.
+
+```bash
+uv pip compile [OPTIONS] <INPUT_FILES>...
+
+-o, --output-file <FILE>     Output file
+--extra <EXTRA>              Include optional dependencies
+--all-extras                 Include all optional dependencies
+--constraint <FILE>, -c      Apply constraints
+--override <FILE>            Apply overrides
+--python <VERSION>           Target Python version
+--python-platform <PLATFORM> Target platform
+--python-version <VERSION>   Python version constraint
+--universal                  Cross-platform requirements
+--no-strip-markers           Preserve environment markers
+--resolution <STRATEGY>      Resolution strategy (highest/lowest/lowest-direct)
+--prerelease <MODE>          Pre-release handling (allow/disallow/if-necessary/if-necessary-or-explicit)
+--upgrade, -U                Allow upgrades
+--upgrade-package <PKG>, -P  Upgrade specific packages
+--generate-hashes            Include package hashes
+--annotation-style <STYLE>   Annotation format (line/split)
+```
+
+### uv pip sync
+
+Install from requirements file.
+
+```bash
+uv pip sync [OPTIONS] <FILE>
+
+--python <PYTHON>            Target Python environment
+--system                     Install into system Python
+--break-system-packages      Allow system modifications
+--target <DIR>               Install to directory
+--no-build                   Don't build from source
+--dry-run                    Show changes without installing
+--reinstall                  Reinstall all packages
+--link-mode <MODE>           Installation link mode (clone/copy/hardlink/symlink)
+--compile-bytecode           Compile to bytecode
+--require-hashes             Require package hashes
+```
+
+### uv pip uninstall
+
+Remove packages.
+
+```bash
+uv pip uninstall [OPTIONS] <PACKAGES>...
+
+--requirement <FILE>, -r     Uninstall from requirements
+--python <PYTHON>            Target Python environment
+--system                     Uninstall from system Python
+```
+
+### uv pip freeze
+
+List installed packages.
+
+```bash
+uv pip freeze [OPTIONS]
+
+--exclude-editable           Exclude editable packages
+--strict                     Fail on missing dependencies
+--python <PYTHON>            Target Python environment
+```
+
+### uv pip list
+
+List installed packages with formatting.
+
+```bash
+uv pip list [OPTIONS]
+
+--editable, -e               Show only editable packages
+--exclude-editable           Exclude editable packages
+--format <FORMAT>            Output format (columns/freeze/json)
+--python <PYTHON>            Target Python environment
+--system                     Target system Python
+```
+
+### uv pip show
+
+Display package information.
+
+```bash
+uv pip show <PACKAGE>
+
+--python <PYTHON>            Target Python environment
+--system                     Target system Python
+```
+
+### uv pip tree
+
+Display dependency tree.
+
+```bash
+uv pip tree [OPTIONS]
+
+--depth <DEPTH>              Maximum display depth
+--prune <PKG>                Prune packages
+--package <PKG>              Show tree for specific package
+--invert                     Show reverse dependencies
+--python <PYTHON>            Target Python environment
+--no-dedupe                  Show all occurrences
+```
+
+### uv pip check
+
+Verify dependencies.
+
+```bash
+uv pip check [OPTIONS]
+
+--python <PYTHON>            Target Python environment
+--system                     Target system Python
+```
+
+## Virtual Environments
+
+### uv venv
+
+Create virtual environment.
+
+```bash
+uv venv [OPTIONS] [PATH]
+
+--python <VERSION>           Python version
+--seed                       Install seed packages (pip, setuptools, wheel)
+--prompt <PROMPT>            Custom environment prompt
+--system-site-packages       Access to system packages
+--relocatable                Relocatable environment
+--allow-existing             Allow existing directory
+--no-project                 Don't detect project
+```
+
+## Build and Publish
+
+### uv build
+
+Build Python packages.
+
+```bash
+uv build [OPTIONS] [SRC]
+
+--sdist                      Build source distribution only
+--wheel                      Build wheel only
+--out-dir <DIR>              Output directory (default: dist/)
+--package <PACKAGE>          Build specific workspace package
+--no-build-isolation         Disable build isolation
+--build-constraint <FILE>    Apply build constraints
+--config-setting <KEY=VALUE> Pass settings to build backend
+```
+
+### uv publish
+
+Upload distributions to package indexes.
+
+```bash
+uv publish [OPTIONS] [FILES]...
+
+--username <USER>, -u        Registry username
+--password <PASS>, -p        Registry password
+--token <TOKEN>, -t          Authentication token
+--publish-url <URL>          Registry URL (default: PyPI)
+--index <NAME>               Named index from config
+--keyring-provider <PROVIDER> Keyring authentication
+--trusted-publishing <MODE>  OIDC trusted publishing (always/if-available/never)
+--check-url <URL>            Verify package existence URL
+--build                      Build packages before publishing
+--no-build                   Publish existing distributions
+```
+
+## Cache Management
+
+### uv cache clean
+
+Clear cache.
+
+```bash
+uv cache clean [OPTIONS] [PACKAGE]
+
+--package <PACKAGE>          Clean specific package only
+```
+
+### uv cache prune
+
+Remove unreachable entries.
+
+```bash
+uv cache prune [OPTIONS]
+
+--ci                         Optimize for CI (keep wheels, remove downloads)
+```
+
+### uv cache dir
+
+Show cache directory path.
+
+```bash
+uv cache dir
+```
+
+## Self Management
+
+### uv self update
+
+Update uv itself.
+
+```bash
+uv self update [OPTIONS]
+
+--version <VERSION>          Update to specific version
+```
+
+### uv self version
+
+Show uv version.
+
+```bash
+uv self version
+uv --version      # Equivalent
+uv -V             # Short form
+```
+
+## Utility Commands
+
+### uv generate-shell-completion
+
+Generate shell completions.
+
+```bash
+uv generate-shell-completion <SHELL>
+
+# Shells: bash, zsh, fish, elvish, powershell
+```
+
+## Index and Resolution Flags
+
+Control package index behavior:
+
+```bash
+--index <NAME>=<URL>         Named package index
+--default-index <URL>        Primary index
+--extra-index-url <URL>      Supplementary index
+--find-links <PATH_OR_URL>   Find-links location
+--no-index                   Ignore all indexes
+--index-strategy <STRATEGY>  Resolution strategy (first-index/unsafe-first-match/unsafe-best-match)
+--resolution <STRATEGY>      Version selection (highest/lowest/lowest-direct)
+--prerelease <MODE>          Pre-release handling
+--exclude-newer <TIMESTAMP>  Exclude packages newer than timestamp
+--no-sources                 Ignore [tool.uv.sources]
+```
+
+## Build Flags
+
+Control build and installation:
+
+```bash
+--no-build                   Don't build from source
+--no-binary <PKG>            Don't use wheels (use :all: for all)
+--only-binary <PKG>          Only use wheels (use :all: for all)
+--no-build-isolation         Disable build isolation
+--no-build-isolation-package <PKG>  Disable for specific packages
+--build-constraint <FILE>    Build dependency constraints
+--config-setting <KEY=VALUE> PEP 517 build backend settings
+--link-mode <MODE>           Installation method (clone/copy/hardlink/symlink)
+--compile-bytecode           Compile to bytecode
+--reinstall                  Reinstall all packages
+--reinstall-package <PKG>    Reinstall specific packages
+--require-hashes             Require package hashes
+```
+
+## Examples
+
+**Initialize and manage project:**
+
+```bash
+uv init myproject --lib
+cd myproject
+uv add requests pytest --dev
+uv lock
+uv sync
+uv run pytest
+```
+
+**Create and run script:**
+
+```bash
+uv init --script analyze.py
+uv add --script analyze.py pandas matplotlib
+uv run analyze.py
+```
+
+**Install and use tools:**
+
+```bash
+uvx ruff check
+uv tool install black
+black myfile.py
+```
+
+**Python version management:**
+
+```bash
+uv python install 3.12
+uv python pin 3.12
+uv run --python 3.11 script.py
+```
+
+**pip interface:**
+
+```bash
+uv pip install flask
+uv pip compile requirements.in -o requirements.txt
+uv pip sync requirements.txt
+```
+
+**Build and publish:**
+
+```bash
+uv build
+uv publish --token $PYPI_TOKEN
+```

skills/uv/references/configuration.md

@@ -0,0 +1,541 @@
+# uv Configuration Reference
+
+Complete configuration guide for uv (v0.9.5).
+
+## Configuration Files
+
+### File Discovery Hierarchy
+
+1. **Project-level** (current or parent directories):
+   - `pyproject.toml` (under `[tool.uv]`)
+   - `uv.toml` (no prefix required)
+
+2. **User-level**:
+   - Linux/macOS: `~/.config/uv/uv.toml`
+   - Windows: `%APPDATA%\uv\uv.toml`
+
+3. **System-level**:
+   - Linux/macOS: `/etc/uv/uv.toml`
+   - Windows: `%PROGRAMDATA%\uv\uv.toml`
+
+### Precedence Order
+
+1. Command-line arguments (highest)
+2. Environment variables
+3. Project-level configuration
+4. User-level configuration
+5. System-level configuration (lowest)
+
+**Note**: `uv.toml` takes precedence over `pyproject.toml` in same directory.
+
+## pyproject.toml Configuration
+
+### Project Metadata
+
+```toml
+[project]
+name = "myproject"
+version = "1.0.0"
+description = "Project description"
+requires-python = ">=3.11"
+dependencies = [
+    "requests>=2.31",
+    "fastapi>=0.115",
+]
+
+# Preferred: Use PEP 735 dependency groups
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "ruff>=0.13.3",
+    "mypy>=1.18.2",
+]
+docs = ["sphinx", "mkdocs"]
+test = ["pytest-cov", "hypothesis"]
+
+# Alternative: project.optional-dependencies (older pattern)
+# [project.optional-dependencies]
+# dev = ["pytest>=8.3", "ruff>=0.5"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+### Core uv Settings
+
+```toml
+[tool.uv]
+# Project management
+managed = true              # uv manages project
+package = true              # Project is Python package
+default-groups = ["dev"]    # Default dependency groups
+
+# Resolution
+resolution = "highest"      # highest/lowest/lowest-direct
+fork-strategy = "requires-python"  # requires-python/fewest
+index-strategy = "first-index"     # first-index/unsafe-first-match/unsafe-best-match
+
+# Environment restrictions
+environments = [
+    "sys_platform == 'darwin'",
+    "sys_platform == 'linux'",
+]
+
+# Dependency constraints
+constraint-dependencies = ["grpcio<1.65"]
+override-dependencies = ["werkzeug==2.3.0"]
+
+# Build configuration
+compile-bytecode = true
+no-build-isolation-package = ["flash-attn"]
+config-settings = { editable_mode = "compat" }
+
+# Cache configuration
+cache-dir = "./.uv_cache"
+cache-keys = [
+    { file = "pyproject.toml" },
+    { git = { commit = true } },
+]
+
+# Network configuration
+concurrent-downloads = 20
+concurrent-builds = 8
+offline = false
+
+# Python management
+python-preference = "managed"  # only-managed/managed/system/only-system
+python-downloads = "automatic"  # automatic/manual/never
+
+# Security
+keyring-provider = "subprocess"  # subprocess/disabled
+allow-insecure-host = ["packages.example.com"]
+
+# Preview features
+preview = true
+```
+
+### Package Indexes
+
+```toml
+[[tool.uv.index]]
+name = "pytorch-cu121"
+url = "https://download.pytorch.org/whl/cu121"
+explicit = true              # Require explicit pinning
+default = false              # Replace PyPI as default
+authenticate = "always"      # always/never
+cache-control = "max-age=3600"
+
+[[tool.uv.index]]
+name = "private-registry"
+url = "https://packages.example.com/simple"
+explicit = true
+```
+
+### Dependency Sources
+
+```toml
+[tool.uv.sources]
+# Workspace dependencies
+internal-lib = { workspace = true }
+
+# Git repositories
+httpx = { git = "https://github.com/encode/httpx" }
+fastapi = { git = "https://github.com/tiangolo/fastapi", branch = "main" }
+requests = { git = "https://github.com/psf/requests", tag = "v2.31.0" }
+
+# Local paths
+local-pkg = { path = "../local-pkg" }
+editable-pkg = { path = "./pkg", editable = true }
+
+# URLs
+package-url = { url = "https://example.com/package.tar.gz" }
+
+# Index pinning
+torch = { index = "pytorch-cu121" }
+
+# Conditional sources
+package = [
+    { index = "linux-index", marker = "sys_platform == 'linux'" },
+    { index = "macos-index", marker = "sys_platform == 'darwin'" },
+]
+```
+
+### Workspace Configuration
+
+```toml
+[tool.uv.workspace]
+members = ["packages/*", "apps/*"]
+exclude = ["packages/deprecated"]
+```
+
+### Build Configuration
+
+```toml
+[tool.uv]
+# Build isolation control
+no-build-isolation-package = ["flash-attn", "deepspeed"]
+
+# Extra build dependencies
+[tool.uv.extra-build-dependencies]
+flash-attn = ["torch", "setuptools"]
+deepspeed = [{ requirement = "torch", match-runtime = true }]
+
+# Build environment variables
+[tool.uv.extra-build-variables]
+flash-attn = { FLASH_ATTENTION_SKIP_CUDA_BUILD = "TRUE" }
+opencv-python = { CMAKE_ARGS = "-DWITH_CUDA=ON" }
+
+# Dependency metadata (for packages without proper metadata)
+[[tool.uv.dependency-metadata]]
+name = "package-name"
+version = "1.0.0"
+requires-dist = ["dependency1>=1.0"]
+requires-python = ">=3.8"
+
+# Per-package build settings
+[tool.uv.config-settings-package]
+numpy = { editable_mode = "compat" }
+scipy = { use_system_blas = "true" }
+
+# Build constraints
+build-constraint-dependencies = ["setuptools==60.0.0"]
+```
+
+### Conflict Resolution
+
+```toml
+[tool.uv]
+# Declare mutually exclusive extras/groups
+conflicts = [
+    [
+        { extra = "cuda" },
+        { extra = "rocm" },
+    ],
+    [
+        { group = "prod" },
+        { group = "dev" },
+    ],
+]
+```
+
+### pip-Specific Settings
+
+```toml
+[tool.uv.pip]
+compile-bytecode = true
+strict = true
+generate-hashes = true
+annotation-style = "line"      # line/split
+extra = ["dev", "test"]
+output-file = "requirements.txt"
+break-system-packages = false
+no-strip-markers = false
+universal = false
+```
+
+## Environment Variables
+
+### Core Configuration
+
+```bash
+# Directories
+UV_CACHE_DIR=/custom/cache
+UV_PROJECT_ENVIRONMENT=.venv
+UV_WORKING_DIRECTORY=/path/to/project
+
+# Configuration
+UV_CONFIG_FILE=/path/to/uv.toml
+UV_NO_CONFIG=1
+
+# Python management
+UV_PYTHON=3.11
+UV_PYTHON_PREFERENCE=managed     # only-managed/managed/system/only-system
+UV_PYTHON_DOWNLOADS=automatic    # automatic/manual/never
+UV_PYTHON_INSTALL_DIR=~/.python
+UV_MANAGED_PYTHON=1
+UV_SYSTEM_PYTHON=1
+```
+
+### Network and Performance
+
+```bash
+# Downloads and builds
+UV_CONCURRENT_DOWNLOADS=20
+UV_CONCURRENT_BUILDS=8
+UV_CONCURRENT_INSTALLS=4
+UV_HTTP_TIMEOUT=30
+UV_HTTP_RETRIES=3
+
+# Network control
+UV_OFFLINE=1
+UV_NO_CACHE=1
+```
+
+### Index Configuration
+
+```bash
+# Primary index
+UV_DEFAULT_INDEX=https://pypi.org/simple
+UV_INDEX_URL=https://pypi.org/simple  # Deprecated
+
+# Additional indexes
+UV_INDEX="name1=https://index1.com name2=https://index2.com"
+UV_EXTRA_INDEX_URL=https://custom.index.com  # Deprecated
+
+# Index authentication
+UV_INDEX_PRIVATE_REGISTRY_USERNAME=user
+UV_INDEX_PRIVATE_REGISTRY_PASSWORD=pass
+```
+
+### Build Configuration
+
+```bash
+# Build control
+UV_COMPILE_BYTECODE=1
+UV_NO_BUILD_ISOLATION=1
+UV_NO_BUILD=1
+UV_NO_BUILD_PACKAGE="numpy scipy"
+UV_NO_BINARY=1
+UV_NO_BINARY_PACKAGE="numpy scipy"
+UV_CONFIG_SETTINGS='{"editable_mode": "compat"}'
+
+# Build constraints
+UV_BUILD_CONSTRAINT=/path/to/constraints.txt
+```
+
+### Resolution Control
+
+```bash
+# Resolution strategy
+UV_RESOLUTION=highest          # highest/lowest/lowest-direct
+UV_PRERELEASE=if-necessary     # allow/disallow/if-necessary/if-necessary-or-explicit
+UV_EXCLUDE_NEWER=2025-01-01T00:00:00Z
+
+# Lock and sync
+UV_FROZEN=1
+UV_LOCKED=1
+UV_NO_SYNC=1
+
+# Dependencies
+UV_DEV=1
+UV_NO_DEV=1
+UV_NO_EDITABLE=1
+```
+
+### Security
+
+```bash
+# Authentication
+UV_KEYRING_PROVIDER=subprocess  # subprocess/disabled
+UV_NATIVE_TLS=1
+
+# Insecure hosts
+UV_INSECURE_HOST="host1.com host2.com"
+
+# Publishing
+UV_PUBLISH_USERNAME=__token__
+UV_PUBLISH_PASSWORD=$PYPI_TOKEN
+UV_PUBLISH_TOKEN=$PYPI_TOKEN
+UV_TRUSTED_PUBLISHING=automatic
+```
+
+### Output Control
+
+```bash
+# Output format
+UV_NO_PROGRESS=1
+UV_NO_WRAP=1
+UV_QUIET=1
+UV_VERBOSE=1
+UV_COLOR=always  # always/never/auto
+UV_LOG_CONTEXT=1
+```
+
+### Tool Management
+
+```bash
+UV_TOOL_DIR=~/.local/share/uv/tools
+UV_TOOL_BIN_DIR=~/.local/bin
+```
+
+### Preview Features
+
+```bash
+UV_PREVIEW=1
+UV_PREVIEW_FEATURES=feature1,feature2
+```
+
+### Advanced Settings
+
+```bash
+# Installation
+UV_LINK_MODE=copy           # clone/copy/hardlink/symlink
+UV_REINSTALL=1
+UV_UPGRADE=1
+UV_NO_INDEX=1
+UV_ISOLATED=1
+
+# Environment files
+UV_ENV_FILE=.env.production
+UV_NO_ENV_FILE=1
+
+# S3 support (preview)
+UV_S3_ENDPOINT_URL=https://s3.amazonaws.com
+
+# Mirrors
+UV_PYTHON_INSTALL_MIRROR=https://mirror.example.com
+UV_PYPY_INSTALL_MIRROR=https://pypy-mirror.example.com
+
+# Debug
+RUST_LOG=uv=debug
+RUST_BACKTRACE=1
+```
+
+## Complete Example Configuration
+
+```toml
+[project]
+name = "myproject"
+version = "1.0.0"
+requires-python = ">=3.11"
+dependencies = ["fastapi>=0.115", "torch"]
+
+# Preferred: Use PEP 735 dependency groups
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "ruff>=0.13.3",
+    "mypy>=1.18.2",
+]
+test = ["pytest-cov", "pytest-asyncio"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+# Project configuration
+managed = true
+package = true
+default-groups = ["dev"]
+
+# Resolution
+resolution = "highest"
+fork-strategy = "requires-python"
+index-strategy = "first-index"
+
+# Environment restrictions
+environments = ["sys_platform == 'linux'"]
+required-environments = ["sys_platform == 'linux' and platform_machine == 'x86_64'"]
+
+# Constraints
+constraint-dependencies = ["grpcio<1.65"]
+override-dependencies = ["werkzeug==2.3.0"]
+build-constraint-dependencies = ["setuptools==60.0.0"]
+
+# Build configuration
+compile-bytecode = true
+no-build-isolation-package = ["flash-attn"]
+config-settings = { editable_mode = "compat" }
+
+# Cache configuration
+cache-dir = "./.uv_cache"
+cache-keys = [
+    { file = "pyproject.toml" },
+    { git = { commit = true } },
+]
+
+# Network
+concurrent-downloads = 20
+concurrent-builds = 8
+
+# Python management
+python-preference = "managed"
+python-downloads = "automatic"
+
+# Security
+keyring-provider = "subprocess"
+
+# Preview features
+preview = true
+
+# Extra build configuration
+[tool.uv.extra-build-dependencies]
+flash-attn = [{ requirement = "torch", match-runtime = true }]
+
+[tool.uv.extra-build-variables]
+flash-attn = { FLASH_ATTENTION_SKIP_CUDA_BUILD = "TRUE" }
+
+# Package sources
+[tool.uv.sources]
+torch = { index = "pytorch-cu121" }
+internal-lib = { workspace = true }
+
+# Custom indexes
+[[tool.uv.index]]
+name = "pytorch-cu121"
+url = "https://download.pytorch.org/whl/cu121"
+explicit = true
+
+[[tool.uv.index]]
+name = "private"
+url = "https://packages.example.com/simple"
+authenticate = "always"
+
+# Workspace configuration
+[tool.uv.workspace]
+members = ["packages/*"]
+exclude = ["packages/deprecated"]
+
+# pip-specific settings
+[tool.uv.pip]
+compile-bytecode = true
+strict = true
+generate-hashes = false
+
+# Conflict resolution
+[[tool.uv.conflicts]]
+extra = ["cuda", "rocm"]
+```
+
+## Configuration Best Practices
+
+1. **Project vs User Config**: Keep project-specific settings in `pyproject.toml`, user preferences in `~/.config/uv/uv.toml`
+2. **Security**: Never commit credentials to version control, use environment variables
+3. **Index Pinning**: Use `explicit = true` for custom indexes to prevent accidents
+4. **Build Isolation**: Only disable for problematic packages, document why
+5. **Cache**: Use project-local cache (`.uv_cache`) for CI reproducibility
+6. **Python Preference**: Use `managed` for consistent team environments
+7. **Lockfiles**: Always commit `uv.lock` for reproducible installs
+8. **Environment Restrictions**: Use `environments` to prevent platform-specific resolution issues
+9. **Preview Features**: Test in development before enabling in production
+
+## uv.toml Format
+
+`uv.toml` uses same structure as `pyproject.toml` but **without** `[tool.uv]` prefix:
+
+```toml
+# uv.toml (no [tool.uv] prefix)
+managed = true
+resolution = "highest"
+compile-bytecode = true
+
+[[index]]
+name = "pytorch"
+url = "https://download.pytorch.org/whl/cpu"
+```
+
+Equivalent to:
+
+```toml
+# pyproject.toml (with [tool.uv] prefix)
+[tool.uv]
+managed = true
+resolution = "highest"
+compile-bytecode = true
+
+[[tool.uv.index]]
+name = "pytorch"
+url = "https://download.pytorch.org/whl/cpu"
+```

skills/uv/references/troubleshooting.md

@@ -0,0 +1,732 @@
+# uv Troubleshooting Guide
+
+Common issues and solutions for uv (v0.9.5).
+
+## Installation and Setup Issues
+
+### uv Command Not Found
+
+**Problem**: `uv: command not found` after installation
+
+**Solutions**:
+
+```bash
+# Check if uv is installed
+which uv
+
+# Check PATH
+echo $PATH
+
+# Add to PATH (Unix)
+export PATH="$HOME/.local/bin:$PATH"
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+
+# Windows: Add to PATH
+# %USERPROFILE%\.local\bin
+
+# Verify installation
+uv --version
+
+# Reinstall if necessary
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Permission Denied
+
+**Problem**: Permission errors during installation or execution
+
+**Solutions**:
+
+```bash
+# Unix: Fix permissions
+chmod +x ~/.local/bin/uv
+
+# Don't use sudo with uv (creates permission issues)
+# Instead use virtual environments
+
+# If accidentally used sudo
+sudo chown -R $USER:$USER ~/.local/share/uv
+sudo chown -R $USER:$USER ~/.cache/uv
+```
+
+## Environment Management Issues
+
+### "Externally Managed" Error
+
+**Problem**: `error: The Python interpreter at ... is externally managed`
+
+**Cause**: Trying to install to uv-managed or system Python with `--system` flag
+
+**Solutions**:
+
+```bash
+# Solution 1: Use virtual environment (recommended)
+uv venv
+source .venv/bin/activate
+uv pip install package
+
+# Solution 2: Use project context
+uv add package  # For projects
+uv run python script.py  # Automatically manages environment
+
+# Solution 3: For scripts with PEP 723 metadata
+uv run --script script.py  # Creates isolated environment
+
+# Don't use --system with uv-managed Python
+```
+
+### Virtual Environment Accidentally Deleted
+
+**Problem**: Running `uv venv` again wipes existing environment
+
+**Cause**: uv doesn't prompt before overwriting `.venv`
+
+**Prevention**:
+
+```bash
+# Check before recreating
+if [ -d ".venv" ]; then
+    echo "Warning: .venv exists"
+    # Use --force if intentional
+    uv venv --force
+else
+    uv venv
+fi
+
+# Or use different path
+uv venv myenv
+```
+
+**Recovery**:
+
+```bash
+# Recreate and reinstall
+uv venv
+uv sync  # If using project with lockfile
+# or
+uv pip install -r requirements.txt
+```
+
+### Can't Activate Virtual Environment
+
+**Problem**: Virtual environment activation fails
+
+**Solutions**:
+
+```bash
+# Unix/macOS - bash/zsh
+source .venv/bin/activate
+
+# Unix/macOS - fish
+source .venv/bin/activate.fish
+
+# Windows - cmd
+.venv\Scripts\activate.bat
+
+# Windows - PowerShell
+.venv\Scripts\Activate.ps1
+
+# If PowerShell execution policy blocks
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+
+# Alternative: Use uv run (no activation needed)
+uv run python script.py
+```
+
+## Dependency Resolution Issues
+
+### Conflicting Dependencies
+
+**Problem**: `error: No solution found when resolving dependencies`
+
+**Diagnosis**:
+
+```bash
+# See detailed resolution output
+uv add package -vvv
+
+# Check dependency tree for conflicts
+uv tree
+
+# Check specific package requirements
+uv pip show package
+```
+
+**Solutions**:
+
+```bash
+# 1. Update packages to resolve conflict
+uv lock --upgrade
+uv sync
+
+# 2. Upgrade specific conflicting package
+uv lock --upgrade-package problematic-package
+
+# 3. Use constraint to force specific version
+# In pyproject.toml:
+[tool.uv]
+constraint-dependencies = ["conflicting-package<2.0"]
+
+# 4. Try different resolution strategy
+[tool.uv]
+resolution = "lowest-direct"  # Instead of "highest"
+
+# 5. Use override for absolute control
+[tool.uv]
+override-dependencies = ["problematic-package==1.5.0"]
+```
+
+### Lockfile Out of Sync
+
+**Problem**: `error: The lockfile is out of sync with the project dependencies`
+
+**Solutions**:
+
+```bash
+# Regenerate lockfile
+uv lock
+
+# If intentional (CI), use --frozen
+uv sync --frozen
+
+# If must match exactly (strict CI), use --locked
+uv sync --locked  # Fails if out of sync
+
+# Update dependencies and lockfile
+uv lock --upgrade
+```
+
+### Pre-release Dependencies
+
+**Problem**: uv won't install pre-release version you need
+
+**Solutions**:
+
+```bash
+# Allow pre-releases in pyproject.toml
+[tool.uv]
+prerelease = "allow"  # or "if-necessary" or "if-necessary-or-explicit"
+
+# Or specify explicitly in dependencies
+dependencies = ["package>=1.0.0a1"]  # Explicit pre-release version
+
+# Command-line override
+uv add --prerelease allow package
+```
+
+## Build Failures
+
+### Build Dependencies Missing
+
+**Problem**: `error: Failed to build` with missing module errors
+
+**Common Errors**:
+
+```text
+ModuleNotFoundError: No module named 'setuptools'
+ModuleNotFoundError: No module named 'distutils'
+ModuleNotFoundError: No module named 'Cython'
+```
+
+**Solutions**:
+
+```bash
+# 1. For modern packages, uv should handle this
+# Check if package is compatible with your Python version
+
+# 2. Install build dependencies manually (rarely needed)
+uv pip install setuptools wheel
+
+# 3. For packages requiring Cython
+[tool.uv.extra-build-dependencies]
+problematic-package = ["Cython"]
+
+# 4. Python 3.12+ removed distutils
+# Update to newer package version
+uv add "package>=newer-version"
+
+# 5. Use pre-built wheels instead
+uv add package --only-binary package
+```
+
+### System Dependencies Missing
+
+**Problem**: Build fails with C compiler or library errors
+
+**Common Errors**:
+
+```text
+error: command 'gcc' failed
+fatal error: Python.h: No such file or directory
+error: openssl/ssl.h: No such file or directory
+```
+
+**Solutions**:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get update
+sudo apt-get install \
+    python3-dev \
+    build-essential \
+    libssl-dev \
+    libffi-dev \
+    libpq-dev \
+    libxml2-dev \
+    libxslt1-dev \
+    libjpeg-dev \
+    zlib1g-dev
+
+# macOS
+xcode-select --install
+brew install openssl postgresql
+
+# RHEL/CentOS/Fedora
+sudo yum groupinstall "Development Tools"
+sudo yum install python3-devel openssl-devel
+
+# Arch Linux
+sudo pacman -S base-devel python
+
+# Verify compiler
+gcc --version
+python3-config --includes
+```
+
+### Build Isolation Issues
+
+**Problem**: Package build fails due to missing dependencies in isolated environment
+
+**Solutions**:
+
+```bash
+# Disable isolation for specific package
+[tool.uv]
+no-build-isolation-package = ["flash-attn", "deepspeed"]
+
+# Provide extra build dependencies
+[tool.uv.extra-build-dependencies]
+flash-attn = ["torch", "setuptools", "ninja"]
+
+# Match runtime version
+[tool.uv.extra-build-dependencies]
+deepspeed = [{ requirement = "torch", match-runtime = true }]
+
+# Set build environment variables
+[tool.uv.extra-build-variables]
+flash-attn = { FLASH_ATTENTION_SKIP_CUDA_BUILD = "TRUE" }
+```
+
+## Package Index Issues
+
+### Authentication Failures
+
+**Problem**: `error: Failed to download` from private registry
+
+**Solutions**:
+
+```bash
+# Set credentials via environment variables
+export UV_INDEX_PRIVATE_USERNAME="user"
+export UV_INDEX_PRIVATE_PASSWORD="password"
+
+# Or use keyring
+export UV_KEYRING_PROVIDER=subprocess
+
+# For PyPI token
+export UV_PUBLISH_TOKEN="pypi-..."
+
+# In pyproject.toml for named index
+[[tool.uv.index]]
+name = "private"
+url = "https://packages.example.com/simple"
+authenticate = "always"
+
+# URL-embedded credentials (less secure)
+[[tool.uv.index]]
+url = "https://user:pass@packages.example.com/simple"
+```
+
+### SSL Certificate Errors
+
+**Problem**: SSL verification fails
+
+**Solutions**:
+
+```bash
+# Use system certificates (recommended)
+export UV_NATIVE_TLS=1
+[tool.uv]
+native-tls = true
+
+# Allow specific insecure host (not recommended)
+export UV_INSECURE_HOST="packages.example.com"
+[tool.uv]
+allow-insecure-host = ["packages.example.com"]
+
+# Update certificates
+# Ubuntu/Debian
+sudo apt-get install ca-certificates
+sudo update-ca-certificates
+
+# macOS
+# Certificates usually managed by system
+```
+
+### Package Not Found
+
+**Problem**: `error: Package 'X' not found`
+
+**Diagnosis**:
+
+```bash
+# Check index configuration
+uv pip install package -vvv
+
+# Verify index URL
+curl https://pypi.org/simple/package-name/
+
+# Check index strategy
+[tool.uv]
+index-strategy = "first-index"  # Try "unsafe-best-match" if needed
+```
+
+**Solutions**:
+
+```bash
+# 1. Check package name spelling
+uv add correct-package-name
+
+# 2. Add appropriate index
+[[tool.uv.index]]
+name = "pytorch"
+url = "https://download.pytorch.org/whl/cu121"
+
+[tool.uv.sources]
+torch = { index = "pytorch" }
+
+# 3. Install from URL directly
+uv add https://files.pythonhosted.org/.../package.whl
+
+# 4. Check Python version compatibility
+requires-python = ">=3.11"  # Package may require newer Python
+```
+
+## Performance Issues
+
+### Slow Downloads
+
+**Problem**: Package downloads are slow
+
+**Solutions**:
+
+```bash
+# Increase concurrent downloads
+export UV_CONCURRENT_DOWNLOADS=50
+[tool.uv]
+concurrent-downloads = 50
+
+# Use mirror
+export UV_PYTHON_INSTALL_MIRROR="https://mirror.example.com"
+
+# Check network
+curl -o /dev/null https://pypi.org/simple/
+
+# Disable progress bars (slight speedup)
+export UV_NO_PROGRESS=1
+```
+
+### Cache Issues
+
+**Problem**: Cache grows too large or contains stale data
+
+**Solutions**:
+
+```bash
+# Check cache size
+du -sh $(uv cache dir)
+
+# Clean entire cache
+uv cache clean
+
+# Prune unreachable entries
+uv cache prune
+
+# CI optimization (keep wheels, remove downloads)
+uv cache prune --ci
+
+# Bypass cache temporarily
+uv sync --no-cache
+
+# Custom cache location
+export UV_CACHE_DIR=/path/to/cache
+[tool.uv]
+cache-dir = "/path/to/cache"
+```
+
+## Script and Tool Issues
+
+### PEP 723 Script Errors
+
+**Problem**: Script with inline metadata won't run
+
+**Solutions**:
+
+```bash
+# Verify metadata block format
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["requests"]
+# ///
+
+# Must use exact format (no spaces before ///)
+# Block must be at top of file (after shebang)
+
+# Run with explicit --script flag
+uv run --script script.py
+
+# Check for syntax errors
+python3 -m py_compile script.py
+
+# Lock script dependencies
+uv lock --script script.py
+
+# Verify with verbose output
+uv run --script script.py -v
+```
+
+### Tool Installation Fails
+
+**Problem**: `uv tool install` fails or tool not in PATH
+
+**Solutions**:
+
+```bash
+# Verify installation
+uv tool list
+uv tool dir
+
+# Check PATH
+echo $PATH | grep -o '\.local/bin'
+
+# Add tools to PATH
+export PATH="$(uv tool dir)/bin:$PATH"
+echo 'export PATH="$(uv tool dir)/bin:$PATH"' >> ~/.bashrc
+
+# Update shell integration
+uv tool update-shell
+
+# Reinstall tool
+uv tool install --force package
+
+# Try with specific Python
+uv tool install --python 3.11 package
+```
+
+## Python Version Issues
+
+### Wrong Python Version Used
+
+**Problem**: uv uses unexpected Python version
+
+**Diagnosis**:
+
+```bash
+# Check detected Python
+uv python find
+
+# Check project pin
+cat .python-version
+
+# Check preference
+echo $UV_PYTHON_PREFERENCE
+```
+
+**Solutions**:
+
+```bash
+# Pin project Python version
+uv python pin 3.11
+
+# Set preference
+export UV_PYTHON_PREFERENCE=managed
+[tool.uv]
+python-preference = "managed"
+
+# Install required Python
+uv python install 3.11
+
+# Specify explicitly
+uv run --python 3.11 script.py
+uv venv --python 3.12
+```
+
+### Python Download Fails
+
+**Problem**: `error: Failed to download Python`
+
+**Solutions**:
+
+```bash
+# Check network connectivity
+curl -I https://github.com/indygreg/python-build-standalone/releases
+
+# Use manual download
+export UV_PYTHON_DOWNLOADS=manual
+
+# Use mirror
+export UV_PYTHON_INSTALL_MIRROR="https://mirror.example.com"
+
+# Disable downloads, use system Python
+export UV_PYTHON_PREFERENCE=system
+```
+
+## Workspace Issues
+
+### Workspace Member Not Found
+
+**Problem**: Workspace member not detected
+
+**Solutions**:
+
+```bash
+# Verify workspace configuration
+[tool.uv.workspace]
+members = ["packages/*"]  # Check glob pattern
+
+# Verify member has pyproject.toml
+ls packages/*/pyproject.toml
+
+# Check exclusions
+[tool.uv.workspace]
+exclude = ["packages/deprecated"]
+
+# Run from workspace root
+cd workspace-root
+uv sync
+
+# Build specific member
+uv build --package member-name
+```
+
+## CI/CD Issues
+
+### CI Cache Not Working
+
+**Problem**: CI doesn't use cache effectively
+
+**Solutions**:
+
+```yaml
+# GitHub Actions
+- uses: actions/cache@v4
+  with:
+    path: ~/.cache/uv
+    key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+    restore-keys: |
+      uv-${{ runner.os }}-
+
+# Use frozen mode in CI
+- run: uv sync --frozen
+
+# Prune cache for CI efficiency
+- run: uv cache prune --ci
+```
+
+### Different Results Locally vs CI
+
+**Problem**: CI builds differently than local
+
+**Solutions**:
+
+```bash
+# Use same Python version
+uv python install $(cat .python-version)
+
+# Use frozen lockfile
+uv sync --frozen
+
+# Use locked for strict matching
+uv sync --locked
+
+# Match Python preference
+export UV_PYTHON_PREFERENCE=managed
+
+# Check environment differences
+uv run python -c "import sys; print(sys.version)"
+uv pip list
+```
+
+## Debugging
+
+### Enable Verbose Logging
+
+```bash
+# Increasing verbosity
+uv sync -v        # Basic verbose
+uv sync -vv       # More verbose
+uv sync -vvv      # Maximum verbosity
+
+# Rust-level debugging
+export RUST_LOG=uv=debug
+export RUST_BACKTRACE=1
+uv sync
+
+# Log to file
+uv sync -vvv 2>&1 | tee uv-debug.log
+```
+
+### Check System Information
+
+```bash
+# uv version and build info
+uv self version
+uv --version
+
+# Python information
+uv python list
+uv python find
+
+# Cache information
+uv cache dir
+du -sh $(uv cache dir)
+
+# Tool information
+uv tool dir
+uv tool list --show-paths
+
+# Project information
+cat pyproject.toml
+cat uv.lock | head -20
+
+# System information
+python3 --version
+which python3
+echo $PATH
+env | grep UV_
+```
+
+## Getting Help
+
+### Report Issues
+
+```bash
+# Gather diagnostic information
+uv --version
+python3 --version
+uname -a  # or systeminfo on Windows
+uv sync -vvv 2>&1 | tee debug.log
+
+# Check existing issues
+# https://github.com/astral-sh/uv/issues
+
+# Create minimal reproduction
+# Include pyproject.toml, uv.lock, commands run, full error output
+```
+
+### Resources
+
+- Documentation: <https://docs.astral.sh/uv/>
+- GitHub Issues: <https://github.com/astral-sh/uv/issues>
+- Discussions: <https://github.com/astral-sh/uv/discussions>
+- Discord: Astral community server