Uv

UV - Python Package Manager Skill

Overview

UV is an extremely fast Python package and project manager written in Rust. This skill provides guidance on using UV for Python development, with particular focus on MCP (Model Context Protocol) server integration and modern tool management workflows.

UV replaces multiple tools: pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more - delivering 10-100x faster performance through intelligent caching and parallel operations.

Version Awareness

Recommended Version: UV 0.9.7+ (Latest as of October 2025)

Before starting, check your UV version:

uv --version

Important Version-Specific Changes:

• UV 0.9.6+: Python 3.14 is now the default (previously 3.13)
• UV 0.9.6+: Free-threaded Python 3.14+ supported without explicit opt-in
• UV 0.9.6+: uv build --clear flag available for cleaning build artifacts
• UV 0.9.7+: Security updates for tar/ZIP archive handling

If your version is older than 0.9.0, upgrade for the best experience:

# Using pip
pip install --upgrade uv

# Or reinstall using official installer
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Unix/Mac
curl -LsSf https://astral.sh/uv/install.sh | sh

See Recent Changes Reference for detailed version information and migration guidance.

When to Use This Skill

Use this skill when:

• Setting up Python virtual environments and managing Python versions
• Installing and managing Python CLI tools (development tools, utilities)
• Running MCP servers with UVX
• Deciding between uv tool install vs uvx for package execution
• Configuring VS Code or other IDEs for MCP server integration
• Migrating from pip, pipx, or poetry to UV
• Troubleshooting UV-related issues

Skip this skill when:

• You need basic Python package installation only (standard pip documentation may suffice)
• Working with legacy Python 2.x projects

Core Concepts

1. UV Commands Overview

UV provides several commands for different use cases:

2. Tool vs UVX Decision Tree

Need to run a Python package?
|
├─ Use daily/frequently?
|  └─ YES → `uv tool install package`
|     Examples: black, pytest, flake8, mypy
|
├─ MCP server?
|  └─ YES → `uvx package` or `uvx --from path script.py`
|     Examples: mcp-server-sqlite, custom MCP servers
|
├─ Testing/one-off execution?
|  └─ YES → `uvx package`
|     Examples: testing new tools, version comparison
|
└─ Local development script?
   └─ YES → `uvx --from . script.py`
      Examples: project-specific scripts

3. MCP Server Execution Patterns

Published Packages (No working directory needed):

{
  "servers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "/path/to/db"]
    }
  }
}

Local Development (Use --from flag):

{
  "servers": {
    "my-server": {
      "command": "uvx",
      "args": [
        "--from", "/absolute/path/to/project",
        "server.py",
        "--config", "config.json"
      ]
    }
  }
}

Key insight: --from flag IS the working directory reference for UVX.

4. Virtual Environment Management

UV works seamlessly with Python's built-in venv:

# Create virtual environment
python -m venv .venv

# Activate (Windows Git Bash)
. .venv/Scripts/activate

# Activate (Windows CMD)
.venv\Scripts\activate.bat

# Activate (Linux/Mac)
source .venv/bin/activate

# Install packages with UV
uv pip install -r requirements.txt

Common Workflows

Development Tools Setup

# Install development tools once
uv tool install black
uv tool install flake8
uv tool install mypy
uv tool install pytest

# Use daily
black .
flake8 src/
mypy src/
pytest tests/

MCP Server Usage

# Test published MCP servers
uvx mcp-server-sqlite --db-path test.db
uvx mcp-server-git --repository /path/to/repo

# Local MCP server development
uvx --from /path/to/project server.py --env config.env

Project Initialization

# Create new project with UV
uv init my-project
cd my-project

# Add dependencies
uv add requests fastapi

# Run project
uv run python main.py

Python Version Management

# List available Python versions
uv python list

# Install default Python version (3.14 in UV 0.9.6+)
uv python install

# Install specific Python version
uv python install 3.12
uv python install 3.13

# Use in project
uv python pin 3.12

Note: As of UV 0.9.6, Python 3.14 is the default version. If you need Python 3.13 or earlier, explicitly specify the version.

Inline Script Dependencies (PEP 723)

UV supports defining dependencies directly in Python script comments:

# /// script
# dependencies = [
#   "requests",
#   "pandas",
# ]
# ///

import requests
import pandas as pd

# Your code here

Run with automatic dependency installation:

# UV installs dependencies automatically
uv run script.py

Benefits:

• Self-contained single-file scripts
• No pyproject.toml needed
• Easy sharing and distribution
• Perfect for utilities and automation

See Inline Script Metadata Reference for comprehensive examples including MCP servers, web applications, data processing, and CLI tools.

Integration Patterns

VS Code MCP Configuration

For .vscode/mcp.json or user settings:

{
  "servers": {
    "published-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "${workspaceFolder}/db.sqlite"]
    },
    "local-dev": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "${workspaceFolder}",
        "src/server.py"
      ]
    }
  }
}

Continue IDE Configuration

For .continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": ["mcp-server-fetch"]
        }
      }
    ]
  }
}

GitHub Actions CI/CD

- name: Setup UV
  uses: astral-sh/setup-uv@v1

- name: Install dependencies
  run: uv pip install -r requirements.txt

- name: Run tests
  run: uv run pytest

Best Practices

Tool Management

DO:

• Use uv tool install for development tools used frequently
• Use uvx for MCP servers (follows community patterns)
• Keep tools isolated in their own environments
• Regularly upgrade tools with uv tool upgrade --all

DON'T:

• Use global pip for CLI tools (causes dependency conflicts)
• Install MCP servers with uv tool install (against community patterns)
• Use uvx for daily development tools (unnecessary overhead)
• Mix pip and uv tool installations

MCP Server Patterns

DO:

• Use UVX for all MCP server execution
• Use --from for local development
• Pin versions for production (package@1.2.3)
• Use environment variables for configuration

DON'T:

• Install MCP servers globally
• Mix working directory approaches
• Use @latest in production (unstable)
• Forget to specify absolute paths with --from

Virtual Environments

DO:

• Use python -m venv for project environments
• Activate before installing packages
• Use uv pip install for faster package installation
• Document activation commands in README

DON'T:

• Install packages globally
• Mix venv and system Python packages
• Forget to activate before development
• Commit .venv directory to version control

Performance Characteristics

UV's performance advantages:

• 10-100x faster than pip for package operations
• Parallel downloads and installations
• Global cache with deduplication
• Rust-powered dependency resolution
• Disk-efficient storage with hard links

Typical operation times:

• Package installation: 100-1000x faster than pip
• Dependency resolution: Near-instant for cached packages
• Virtual environment creation: <1 second
• UVX first run: Package download time + execution
• UVX cached run: <1 second startup

Troubleshooting

Common Issues

"spawn uvx ENOENT" Error:

• UV/UVX not in PATH
• Solution: Reinstall UV or add to PATH manually

Package Not Found:

• Check package name on PyPI
• For local development, verify --from path
• Ensure pyproject.toml exists

Permission Errors:

• UV cache directory not writable
• Solution: Check permissions on ~/.cache/uv/

Version Conflicts:

• Multiple Python versions
• Solution: Use uv python pin to set project version

See detailed troubleshooting in:

• Installation & Setup Reference
• Tool Management Reference
• MCP Integration Reference

Reference Documentation

This skill includes detailed reference documentation:

1. [Recent Changes](references/recent-changes.md) ⭐ NEW

• Latest version information (0.9.7+)
• Python 3.14 default and free-threading support
• New features and breaking changes
• Version compatibility matrix
• Upgrade guidance

2. [Installation & Setup](references/installation-and-setup.md)

• Installation methods (Windows, Linux, Mac)
• Virtual environment setup
• Platform-specific considerations

3. [Tool Management](references/tool-management.md)

• UV tool install vs UVX comparison
• Persistent vs temporary execution
• Maintenance workflows

4. [MCP Integration](references/mcp-integration.md)

• Published package patterns
• Local development with --from
• VS Code and IDE configuration

5. [Python Environment](references/python-environment.md)

• Python version management
• System paths (pyenv, uv, system)
• Cross-platform compatibility

6. [Inline Script Metadata](references/inline-script-metadata.md)

• PEP 723 inline dependencies in comments
• Single-file scripts with automatic dependency management
• MCP servers, web apps, and CLI tools
• Best practices and troubleshooting

7. [Examples](examples/README.md)

• Real-world GitHub configurations
• Common workflow patterns
• Anti-patterns to avoid

External Resources

• UV Official Documentation: <https://docs.astral.sh/uv/>
• UV GitHub Repository: <https://github.com/astral-sh/uv>
• MCP Official Documentation: <https://modelcontextprotocol.io/>
• MCP Servers Repository: <https://github.com/modelcontextprotocol/servers>
• VS Code MCP Support: <https://code.visualstudio.com/docs/copilot/chat/mcp-servers>

Migration Guides

From pip

# Old way
pip install requests

# New way
uv pip install requests

From pipx

# Old way
pipx install black

# New way
uv tool install black

From poetry

# Old way
poetry add requests
poetry install

# New way
uv add requests
uv sync

Summary

UV provides a unified, fast, and modern approach to Python package management. The key to effective UV usage is:

1. Understand the tool landscape: uv pip, uv tool, uvx each serve specific purposes 2. Follow community patterns: Use UVX for MCP servers, uv tool for development tools 3. Leverage isolation: Each tool gets its own environment preventing conflicts 4. Use --from for local development: Essential pattern for MCP server development 5. Keep tools updated: Regular maintenance prevents issues

By following these patterns and utilizing the reference documentation, you'll have a clean, efficient, and maintainable Python development environment.

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is a template repository for creating custom Claude Code skills. It provides a structured framework for building skills that extend Claude Code's capabilities with specialized knowledge, workflows, or tool integrations.

Core Architecture

Skill Structure

Claude Code skills follow a progressive disclosure pattern with three resource types:

1. SKILL.md (Required) - Main skill configuration with YAML frontmatter

• Contains name and description fields that determine when Claude activates the skill
• Uses imperative/infinitive form (verb-first instructions) throughout
• Kept lean (<5k words), detailed info moved to references/

2. scripts/ - Executable code for deterministic, reusable operations

• Used when the same code is repeatedly rewritten
• Can be executed without loading into context

3. references/ - Documentation loaded into context as needed

• For schemas, API docs, domain knowledge, policies
• Keeps SKILL.md focused while providing detailed information

4. assets/ - Files used in output (NOT loaded into context)

• Templates, images, boilerplate, fonts
• Copied/modified in the final output

GitHub Actions Workflow

The repository includes .github/workflows/release-skill.yml which automatically:

• Extracts version from VERSION file
• Validates SKILL.md structure (frontmatter with name/description)
• Builds skill distribution ZIP
• Attaches to GitHub releases

Development Commands

Testing the Skill Locally

Install skill to Claude Code skills directory:

# Windows (Git Bash)
cp -r . "$USERPROFILE/.claude/skills/your-skill-name"

# Unix/Mac
cp -r . ~/.claude/skills/your-skill-name

Test activation by asking Claude questions that match the skill description.

Markdown Linting

The repository uses markdownlint-cli2 with line length checks disabled:

# Configuration in .markdownlint-cli2.jsonc
# MD013 (line length) is disabled to prevent linter warnings on long lines

Git Configuration

For new repositories, configure git user locally:

git config --local user.name "your-username"
git config --local user.email "your-email@users.noreply.github.com"

Release Process

1. Update VERSION file with new version (e.g., 1.0.0) 2. Commit and push: git commit -m "Release v1.0.0" && git push 3. Create release: gh release create v1.0.0 --generate-notes 4. GitHub Actions automatically builds and attaches skill ZIP

See docs/tasks/release/how-to-release.md for detailed instructions.

Important Files

• SKILL.md - Main skill file with YAML frontmatter (name, description)
• VERSION - Single version number for releases (e.g., 0.0.1)
• README.md - User-facing documentation and installation instructions
• SETUP.md - Step-by-step setup guide for customizing the template
• .markdownlint-cli2.jsonc - Markdown linter config (MD013 disabled)
• docs/tasks/release/how-to-release.md - Release workflow documentation
• docs/tasks/tests/how-to-test-skill.md - Testing framework and test cases

Skill Development Best Practices

SKILL.md Description Field

The description field determines when Claude activates the skill. Make it:

• Specific about trigger words users might say
• Clear about scenarios when to use the skill
• Include file types, actions, or topics relevant to the skill
• Use third-person form: "This skill should be used when..."

Example:

---
name: docker-helper
description: This skill should be used when the user asks about Docker containers, needs to run docker commands, or wants to manage Docker images and containers. Use when queries mention docker, containerization, or container management.
---

Writing Style

• Use imperative/infinitive form (verb-first instructions) throughout SKILL.md
• Good: "Run the script to process files"
• Bad: "You should run the script" or "You can run the script"
• Keep SKILL.md focused and concise (<5k words)
• Move detailed documentation to references/ files
• Provide real examples, not hypothetical ones

Bundled Resources Guidelines

When to include scripts/

• Code is repeatedly rewritten by Claude
• Deterministic behavior is critical
• Complex logic that shouldn't be regenerated

When to include references/

• Detailed schemas, API docs, policies
• Domain-specific knowledge
• Information that informs Claude's process
• For files >10k words, include grep patterns in SKILL.md

When to include assets/

• Templates, images, boilerplate
• Files that will be copied/modified in output
• NOT loaded into context, used in final deliverables

Testing Approach

Follow the framework in docs/tasks/tests/how-to-test-skill.md:

1. Install skill locally 2. Test activation with various phrasings 3. Verify core functionality 4. Test error handling 5. Validate documentation accuracy

Create specific test cases for each skill feature with expected inputs/outputs.

Common Workflows

Creating a New Skill from Template

1. Update SKILL.md frontmatter (name and description) 2. Customize SKILL.md content (purpose, usage, prerequisites) 3. Add implementation (scripts, references, or assets) 4. Update README.md with skill-specific information 5. Update VERSION file (start with 0.0.1) 6. Test locally by installing to Claude skills directory 7. Initialize git and push to GitHub 8. Create release when ready

See SETUP.md for complete step-by-step instructions.

Validation Before Release

Required checks:

• SKILL.md has valid YAML frontmatter with name and description
• VERSION file exists with semantic version number
• README.md is customized (no template placeholders)
• Skill installs correctly to ~/.claude/skills/
• Claude activates skill when expected
• All documented commands/scripts work
• Documentation matches actual behavior

Troubleshooting

Skill Doesn't Activate

1. Verify SKILL.md has valid YAML frontmatter: head -10 SKILL.md 2. Check description is specific with trigger words 3. Try explicit request: "Use the [skill-name] skill to..." 4. Restart Claude Code (skills loaded on startup)

GitHub Actions Release Fails

Common issues:

• VERSION file missing or empty
• SKILL.md missing YAML frontmatter
• Invalid frontmatter (missing name or description)

Check workflow logs: gh run view --log

Scripts Don't Execute

1. Verify scripts are executable: chmod +x scripts/*.py 2. Check required tools installed: which python, which jq, etc. 3. Test script manually: python scripts/example_script.py

Documentation Structure

docs/
├── guides/              # Additional documentation (optional)
│   └── README.md
└── tasks/
    ├── release/
    │   └── how-to-release.md    # Release workflow
    └── tests/
        └── how-to-test-skill.md # Testing framework

Version Numbering

Follow semantic versioning (MAJOR.MINOR.PATCH):

• 0.0.1 - Initial development
• 0.1.0 - First feature complete
• 1.0.0 - First stable release
• 1.1.0 - New feature (backward compatible)
• 1.1.1 - Bug fix
• 2.0.0 - Breaking change

References

• Claude Code Skills Documentation
• Skill Authoring Best Practices
• skill-creator Skill - Official skill creation tool

Additional Resources

This directory contains supplementary documentation for the UV skill.

Claude Code Skills Documentation

Learn more about using and creating Claude Code skills:

• Claude Code Skills Documentation
• Skill Best Practices
• Skill Creation Guide

UV Documentation

Official UV documentation and resources:

• UV Official Documentation
• UV GitHub Repository
• UV Installation Guide
• UV Command Reference
• UV Python Project Guide

MCP Documentation

Model Context Protocol resources for MCP server integration:

• MCP Official Documentation
• MCP Specification
• MCP Servers Repository
• VS Code MCP Configuration
• Continue IDE MCP Support

Testing the UV Skill

This guide provides specific test cases for manually testing the UV skill to ensure it works correctly with Claude Code.

Overview

Testing focuses on verifying that Claude Code correctly invokes the UV skill and provides accurate guidance for Python package management, tool installation, MCP server integration, and virtual environment management.

Prerequisites

• [ ] UV skill installed in ~/.claude/skills/uv/ or $USERPROFILE/.claude/skills/uv/
• [ ] UV installed and accessible in PATH (uv --version works)
• [ ] Python 3.8+ installed
• [ ] Claude Code configured and running

Installation for Testing

Claude Code CLI

# Windows (Git Bash)
cd "$USERPROFILE/.claude/skills"
cp -r /path/to/uv-skill/ ./uv/

# Unix/Mac
cd ~/.claude/skills
cp -r /path/to/uv-skill/ ./uv/

Verify Installation

# Check skill directory
ls -la ~/.claude/skills/uv/

# Verify SKILL.md exists
cat ~/.claude/skills/uv/SKILL.md | head -20

Test Scenarios

Test Case 1: Basic UV Installation Guidance

User Request:

"How do I install UV on Windows?"

Alternative Variations:

• "Set up UV for Python development"
• "Install UV package manager"
• "Get started with UV"

Expected Behavior:

1. Claude should recognize this matches the UV skill 2. Claude should provide installation instructions for Windows 3. Should mention adding UV to PATH 4. Should reference the Installation & Setup reference document

Expected Output:

• Installation command (e.g., PowerShell installer or Scoop)
• PATH configuration instructions
• Verification command (uv --version)

Validation:

• [ ] Skill activated automatically
• [ ] Platform-specific installation provided
• [ ] PATH setup instructions included
• [ ] Verification step included

Test Case 2: Tool Install vs UVX Decision

User Request:

"Should I use uv tool install or uvx for Black formatter?"

Alternative Variations:

• "How to install Black with UV?"
• "Difference between uv tool install and uvx"
• "Best way to install development tools with UV"

Expected Behavior:

1. Claude should recognize this involves tool management decision 2. Should explain uv tool install is appropriate for daily tools 3. Should provide example: uv tool install black 4. Should explain UVX is for temporary/one-off execution

Expected Output:

For Black formatter (daily development tool):
- Use: uv tool install black
- Reason: Used frequently, benefits from persistent installation

Validation:

• [ ] Correctly recommends uv tool install for Black
• [ ] Explains rationale (frequent use)
• [ ] Provides example command
• [ ] References decision tree if needed

Test Case 3: MCP Server Configuration

User Request:

"How do I configure mcp-server-sqlite with uvx in VS Code?"

Alternative Variations:

• "Set up MCP server with UV in VS Code"
• "Configure .vscode/mcp.json for UV"
• "Run MCP server using UVX"

Expected Behavior:

1. Claude should recognize this is MCP integration 2. Should provide VS Code configuration example 3. Should use uvx command (not uv tool install) 4. Should show proper JSON structure for .vscode/mcp.json

Expected Output:

{
  "servers": {
    "sqlite": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "${workspaceFolder}/db.sqlite"]
    }
  }
}

Validation:

• [ ] Uses uvx (not uv tool install)
• [ ] Proper JSON structure
• [ ] Includes required fields (type, command, args)
• [ ] Uses VS Code variables if appropriate

Test Case 4: Local MCP Server Development

User Request:

"I'm developing a custom MCP server locally. How do I configure it with UV?"

Alternative Variations:

• "Run local Python MCP server with UVX"
• "Use --from flag with UVX for local development"
• "Configure local MCP server in VS Code with UV"

Expected Behavior:

1. Claude should recognize local development scenario 2. Should recommend --from flag approach 3. Should provide example configuration 4. Should emphasize absolute paths

Expected Output:

{
  "servers": {
    "my-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "/absolute/path/to/project",
        "server.py",
        "--config", "config.json"
      ]
    }
  }
}

Validation:

• [ ] Uses --from flag correctly
• [ ] Explains absolute path requirement
• [ ] Proper argument structure
• [ ] References MCP Integration reference if needed

Test Case 5: Virtual Environment Setup

User Request:

"How do I create and activate a virtual environment with UV?"

Alternative Variations:

• "Set up Python venv with UV"
• "Create virtual environment for Python project"
• "Activate virtual environment on Windows"

Expected Behavior:

1. Claude should provide venv creation command 2. Should provide platform-specific activation instructions 3. Should explain using uv pip install in activated environment 4. Should mention faster performance vs regular pip

Expected Output:

# Create virtual environment
python -m venv .venv

# Activate (Windows Git Bash)
. .venv/Scripts/activate

# Install packages with UV
uv pip install -r requirements.txt

Validation:

• [ ] Shows venv creation
• [ ] Platform-specific activation
• [ ] Shows UV usage in activated environment
• [ ] Mentions performance benefits

Test Case 6: Python Version Management

User Request:

"How do I install and use Python 3.12 with UV?"

Alternative Variations:

• "Manage Python versions with UV"
• "Switch Python version in UV project"
• "Install specific Python version"

Expected Behavior:

1. Claude should explain Python version installation 2. Should show uv python install command 3. Should show uv python pin for project-specific version 4. Should mention listing available versions

Expected Output:

# Install Python 3.12
uv python install 3.12

# Pin to project
uv python pin 3.12

# List available versions
uv python list

Validation:

• [ ] Shows installation command
• [ ] Shows pinning command
• [ ] Mentions listing versions
• [ ] Explains project-specific configuration

Test Case 7: Inline Script Dependencies (PEP 723)

User Request:

"How can I create a single Python script with dependencies using UV?"

Alternative Variations:

• "Use PEP 723 inline dependencies with UV"
• "Self-contained Python script with dependencies"
• "UV inline script metadata"

Expected Behavior:

1. Claude should explain PEP 723 inline dependencies 2. Should provide example with comment-based dependencies 3. Should show uv run script.py command 4. Should reference Inline Script Metadata reference

Expected Output:

# /// script
# dependencies = [
#   "requests",
#   "pandas",
# ]
# ///

import requests
import pandas as pd

Run with: uv run script.py

Validation:

• [ ] Shows correct comment syntax
• [ ] Explains automatic dependency installation
• [ ] Provides execution command
• [ ] Mentions reference document

Test Case 8: Migration from pip/pipx

User Request:

"I'm currently using pip and pipx. How do I migrate to UV?"

Alternative Variations:

• "Switch from pipx to UV"
• "Convert pip commands to UV"
• "Migrate Python tools to UV"

Expected Behavior:

1. Claude should provide migration comparison 2. Should show before/after examples 3. Should explain benefits (speed, isolation) 4. Should cover both package and tool installation

Expected Output:

# Old way (pip)
pip install requests

# New way (UV)
uv pip install requests

# Old way (pipx)
pipx install black

# New way (UV)
uv tool install black

Validation:

• [ ] Shows clear before/after comparison
• [ ] Covers both pip and pipx migration
• [ ] Explains benefits
• [ ] Mentions tool isolation

Test Case 9: Error Handling - UV Not Found

Setup:

Simulate scenario where UV is not installed or not in PATH.

User Request:

"I'm getting 'spawn uvx ENOENT' error when running MCP server"

Alternative Variations:

• "UV command not found"
• "uvx not in PATH"
• "Can't find UV executable"

Expected Behavior:

1. Claude should recognize this as PATH/installation issue 2. Should suggest verifying UV installation 3. Should provide PATH verification commands 4. Should suggest reinstallation if needed

Expected Output:

• Check UV installation: uv --version
• Check PATH configuration
• Reinstallation instructions if needed
• Link to troubleshooting in references

Validation:

• [ ] Identifies PATH/installation issue
• [ ] Provides verification commands
• [ ] Suggests solutions
• [ ] References troubleshooting documentation

Test Case 10: Advanced - GitHub Actions Integration

User Request:

"How do I use UV in GitHub Actions for CI/CD?"

Alternative Variations:

• "Set up UV in GitHub Actions workflow"
• "CI/CD configuration for UV"
• "Install dependencies with UV in Actions"

Expected Behavior:

1. Claude should provide GitHub Actions workflow example 2. Should use official astral-sh/setup-uv action 3. Should show dependency installation and test execution 4. Should explain benefits for CI performance

Expected Output:

- name: Setup UV
  uses: astral-sh/setup-uv@v1

- name: Install dependencies
  run: uv pip install -r requirements.txt

- name: Run tests
  run: uv run pytest

Validation:

• [ ] Uses official action
• [ ] Shows proper workflow structure
• [ ] Includes dependency installation
• [ ] Shows test execution example

Test Case 11: Python 3.14 Default Version (UV 0.9.6+)

User Request:

"What Python version will UV install by default?"

Alternative Variations:

• "Install Python with UV without specifying version"
• "What's the default Python version in UV?"
• "Create new UV project - which Python version?"

Expected Behavior:

1. Claude should mention Python 3.14 is now the default (as of UV 0.9.6) 2. Should explain how to check UV version 3. Should show how to explicitly pin to different version if needed 4. Should reference the Recent Changes documentation

Expected Output:

# Check UV version first
uv --version

# UV 0.9.6+ installs Python 3.14 by default
uv python install
# Installs Python 3.14

# To use a specific version
uv python install 3.13
uv python pin 3.13

Validation:

• [ ] Mentions Python 3.14 as default (for UV 0.9.6+)
• [ ] Shows version check command
• [ ] Explains how to pin specific version
• [ ] References version compatibility

Test Case 12: Free-Threaded Python Support (UV 0.9.6+)

User Request:

"How do I use free-threaded Python with UV?"

Alternative Variations:

• "Does UV support Python without GIL?"
• "Install free-threaded Python 3.14"
• "How to enable parallel threading in Python with UV?"

Expected Behavior:

1. Claude should explain free-threaded Python concept (PEP 703) 2. Should mention it's available in Python 3.14+ without explicit opt-in 3. Should provide example showing parallel execution benefits 4. Should reference Recent Changes documentation

Expected Output:

# Install Python 3.14 (includes free-threading support)
uv python install 3.14

# Verify installation
uv python list

# Use in project
uv python pin 3.14

Example showing benefits:

# Multi-threaded code runs in true parallel with Python 3.14+
import threading

def cpu_task():
    result = sum(i**2 for i in range(10_000_000))
    return result

threads = [threading.Thread(target=cpu_task) for _ in range(4)]
for t in threads:
    t.start()
for t in threads:
    t.join()

Validation:

• [ ] Explains free-threaded Python concept
• [ ] Mentions no explicit opt-in needed (UV 0.9.6+)
• [ ] Shows installation command
• [ ] Provides practical example
• [ ] Explains performance benefits

Test Case 13: Build --clear Flag (UV 0.9.6+)

User Request:

"How do I clean old build artifacts before building with UV?"

Alternative Variations:

• "Remove dist folder before building"
• "Clean build with UV"
• "UV build with automatic cleanup"

Expected Behavior:

1. Claude should mention --clear flag added in UV 0.9.6 2. Should show command usage 3. Should explain it removes old artifacts automatically 4. Should mention version requirement

Expected Output:

# Check UV version (needs 0.9.6+)
uv --version

# Build with automatic cleanup
uv build --clear

# Old workflow (no longer needed)
# rm -rf dist/
# uv build

Validation:

• [ ] Mentions --clear flag
• [ ] Shows correct command syntax
• [ ] Explains automatic cleanup behavior
• [ ] Mentions version requirement (0.9.6+)

Test Case 14: UV Version Check and Upgrade

User Request:

"How do I check if my UV is up to date?"

Alternative Variations:

• "Check UV version"
• "Upgrade UV to latest version"
• "What version of UV do I have?"

Expected Behavior:

1. Claude should show version check command 2. Should provide upgrade instructions 3. Should mention latest version (0.9.7 as of October 2025) 4. Should reference Recent Changes documentation

Expected Output:

# Check current version
uv --version

# Upgrade using pip
pip install --upgrade uv

# Or reinstall using official installer
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Unix/Mac
curl -LsSf https://astral.sh/uv/install.sh | sh

Validation:

• [ ] Shows version check command
• [ ] Provides upgrade instructions
• [ ] Mentions latest stable version
• [ ] Shows platform-specific installers

Test Case 15: Version-Specific Feature Guidance

User Request:

"I'm using UV 0.9.5. Can I use the --clear flag?"

Alternative Variations:

• "What features are available in my UV version?"
• "Do I need to upgrade UV for Python 3.14?"
• "Version compatibility check"

Expected Behavior:

1. Claude should identify that --clear requires UV 0.9.6+ 2. Should recommend upgrading if needed 3. Should explain what features are available in user's version 4. Should reference version compatibility matrix

Expected Output:

The --clear flag was added in UV 0.9.6. Your version (0.9.5) doesn't support it yet.

To use this feature, upgrade UV:

pip install --upgrade uv

After upgrading, you can use:
uv build --clear

Validation:

• [ ] Correctly identifies version requirements
• [ ] Recommends upgrade when needed
• [ ] Provides clear upgrade path
• [ ] References compatibility information

Troubleshooting

Skill Doesn't Activate

Symptoms:

• Claude doesn't use the UV skill when expected
• Claude says "I don't have access to that information"

Checks:

1. Verify installation:

   ls ~/.claude/skills/uv/SKILL.md

2. Check SKILL.md format:

   head -10 ~/.claude/skills/uv/SKILL.md

Should show:

   ---
   name: uv
   description: This skill should be used when...
   ---

3. Try being explicit: Instead of: "How do I install packages?" Try: "Use the UV skill to help me install Python packages"

4. Restart Claude Code:

• Skills are loaded on startup
• Restart may be needed after installation

Incorrect Guidance Provided

Symptoms:

• Claude recommends uv tool install for MCP servers (incorrect)
• Claude suggests wrong configuration pattern

Checks:

1. Verify skill version: Check VERSION file and ensure it's the latest

2. Check reference documents: Ensure references/ directory is included and accessible

3. Report issue: If guidance is consistently incorrect, report in GitHub issues

Testing Checklist

Pre-Test Setup

• [ ] Skill installed in correct directory
• [ ] UV installed and in PATH
• [ ] SKILL.md has valid frontmatter
• [ ] Reference documents present

Core Functionality

• [ ] Test Case 1: Basic UV installation ✓
• [ ] Test Case 2: Tool install vs UVX ✓
• [ ] Test Case 3: MCP server configuration ✓
• [ ] Test Case 4: Local MCP development ✓
• [ ] Test Case 5: Virtual environment setup ✓
• [ ] Test Case 6: Python version management ✓
• [ ] Test Case 7: Inline script dependencies ✓
• [ ] Test Case 8: Migration guidance ✓
• [ ] Test Case 9: Error handling ✓
• [ ] Test Case 10: GitHub Actions integration ✓

Recent Features (UV 0.9.6+)

• [ ] Test Case 11: Python 3.14 default version ✓
• [ ] Test Case 12: Free-threaded Python support ✓
• [ ] Test Case 13: Build --clear flag ✓
• [ ] Test Case 14: UV version check and upgrade ✓
• [ ] Test Case 15: Version-specific feature guidance ✓

Documentation Quality

• [ ] SKILL.md description triggers skill correctly
• [ ] Instructions are clear and accurate
• [ ] Examples work as documented
• [ ] References are accessible and relevant

Test Results Template

# UV Skill Test Results

**Date:** YYYY-MM-DD
**Platform:** Windows/macOS/Linux
**Claude Code Version:** X.X.X
**UV Version:** X.X.X
**Tester:** [Name]

## Environment

- OS: [OS details]
- Shell: [bash/zsh/Git Bash/PowerShell]
- Python Version: [version]
- UV Version: [version]

## Test Results

| Test Case | Status | Notes |
|-----------|--------|-------|
| 1. Basic UV installation | ✓ PASS | |
| 2. Tool install vs UVX | ✓ PASS | |
| 3. MCP server config | ✓ PASS | |
| 4. Local MCP development | ✓ PASS | |
| 5. Virtual environment | ✓ PASS | |
| 6. Python version mgmt | ✓ PASS | |
| 7. Inline script deps | ✓ PASS | |
| 8. Migration guidance | ✓ PASS | |
| 9. Error handling | ✓ PASS | |
| 10. GitHub Actions | ✓ PASS | |
| 11. Python 3.14 default | ✓ PASS | |
| 12. Free-threaded Python | ✓ PASS | |
| 13. Build --clear flag | ✓ PASS | |
| 14. Version check/upgrade | ✓ PASS | |
| 15. Version-specific features | ✓ PASS | |

## Issues Found

[List any issues with detailed descriptions]

## Recommendations

[Suggestions for improvements to SKILL.md or reference documents]

## Overall Assessment

☐ Ready for release
☐ Needs minor fixes
☐ Needs major revision

Best Practices

1. Test Incrementally

• Test after each change to SKILL.md or references
• Don't build everything before testing
• Catch issues early

2. Use Real Scenarios

• Test with actual use cases from UV documentation
• Get feedback from real UV users
• Verify against official UV patterns

3. Cross-Platform Testing

• Test on Windows (Git Bash and PowerShell)
• Test on macOS (if available)
• Test on Linux (if available)
• Document platform-specific issues

4. Version Testing

• Test each version before release
• Keep test results for each version
• Track regression issues

5. Reference Document Testing

• Verify references load correctly
• Check that grep patterns work
• Ensure examples in references are accurate

Resources

• UV Official Documentation
• Claude Code Skills Documentation
• Skill Authoring Best Practices

How to Release Your Skill

This guide explains how to create a new release using GitHub Actions.

Prerequisites

• Repository pushed to GitHub
• GitHub Actions workflow configured (.github/workflows/release-skill.yml)
• gh CLI installed and authenticated
• Git configured with proper credentials

Release Process

Step 1: Update Version

Update the VERSION file with the new release version:

# Navigate to repository
cd /path/to/your-skill-name

# Update version (example: 1.0.0)
echo "1.0.0" > VERSION

# Verify version
cat VERSION

Step 2: Commit Version Change

# Stage version file
git add VERSION

# Commit with clear message
git commit -m "Release v1.0.0"

# Push to GitHub
git push origin main

Step 3: Create GitHub Release

Using gh CLI (Recommended):

# Create release with auto-generated notes
gh release create v1.0.0 \
  --title "v1.0.0" \
  --generate-notes

# OR with custom notes
gh release create v1.0.0 \
  --title "Your Skill v1.0.0" \
  --notes "First stable release.

## Features
- Feature 1
- Feature 2
- Feature 3

## Installation
Download {skill-name}-skill.zip from assets and extract to your Claude Code skills directory."

Using GitHub Web UI:

1. Go to your repository releases page 2. Click "Draft a new release" 3. Click "Choose a tag" → Type v1.0.0 → "Create new tag: v1.0.0 on publish" 4. Set "Release title" to v1.0.0 5. Click "Generate release notes" or write custom notes 6. Click "Publish release"

Step 4: Monitor GitHub Actions

GitHub Actions will automatically:

1. Checkout code at the release tag 2. Extract version from VERSION file 3. Verify skill structure (SKILL.md with frontmatter) 4. Build distribution (create {skill-name}-skill.zip) 5. Validate archive structure 6. Upload artifact (90-day retention) 7. Attach to release

Monitor the workflow:

# Watch workflow status
gh run watch

# OR view in browser
gh run view --web

Step 5: Verify Release

# Open release in browser
gh release view v1.0.0 --web

# View release details
gh release view v1.0.0

Verify assets:

1. Check release page has {skill-name}-skill.zip attached 2. Download and test:

# Download release asset
gh release download v1.0.0

# Test extraction
mkdir -p test-install
unzip {skill-name}-skill.zip -d test-install

# Verify structure
ls -la test-install/{skill-name}/

Version Numbering

Follow Semantic Versioning:

• MAJOR.MINOR.PATCH (e.g., 1.0.0)
• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes (backward compatible)

Examples:

• 0.0.1 - Initial development
• 0.1.0 - First feature complete
• 1.0.0 - First stable release
• 1.1.0 - Added new feature
• 1.1.1 - Bug fix
• 2.0.0 - Breaking change

Troubleshooting

Workflow Fails

# Check logs
gh run list --workflow=release-skill.yml
gh run view <failed-run-id> --log

Common issues:

• VERSION file not found → Ensure VERSION exists in root
• SKILL.md validation failed → Check YAML frontmatter
• Archive validation failed → Verify required files exist

Re-running Failed Release

# Delete and recreate release
gh release delete v1.0.0 --yes
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0
# Then recreate release (Step 3)

Release Checklist

• [ ] Update VERSION file
• [ ] Update README.md if needed
• [ ] Test locally
• [ ] Commit all changes
• [ ] Push to GitHub
• [ ] Create release tag
• [ ] Monitor GitHub Actions
• [ ] Verify release assets
• [ ] Test installation from release ZIP

Additional Resources

• GitHub Actions Documentation
• GitHub CLI Reference
• Semantic Versioning

Anti-Patterns to Avoid

Overview

Common mistakes to avoid when using UV.

Global pip Installs

DON'T:

# BAD: Global pip installs
pip install black flake8 mypy
# Problems:
# - Dependency conflicts
# - Pollutes global Python
# - Difficult to uninstall
# - Version conflicts with projects

DO:

# GOOD: UV tool installs
uv tool install black
uv tool install flake8
uv tool install mypy
# Benefits:
# - Isolated environments
# - No conflicts
# - Easy management
# - Clean uninstall

Installing MCP Servers with uv tool

DON'T:

# BAD: Installing MCP servers persistently
uv tool install mcp-server-sqlite
# Problems:
# - Goes against community patterns
# - Less flexible for testing
# - Requires reinstall for updates
# - Not what docs recommend

DO:

# GOOD: Use uvx for MCP servers
uvx mcp-server-sqlite --db-path /path/to/db

# In VS Code config:
{
  "command": "uvx",
  "args": ["mcp-server-sqlite", "--db-path", "/path/to/db"]
}
# Benefits:
# - Follows community patterns
# - Easy version testing
# - Matches documentation
# - Immediate updates

Using uvx for Daily Tools

DON'T:

# BAD: Using uvx for frequently used tools
uvx black my_file.py  # Every time
uvx flake8 .         # Every time
uvx pytest          # Every time
# Problems:
# - Unnecessary overhead
# - Slower execution
# - Cache management needed
# - Not optimal use case

DO:

# GOOD: Install tools with uv tool
uv tool install black flake8 pytest

# Then use directly
black my_file.py
flake8 .
pytest
# Benefits:
# - Instant execution
# - No overhead
# - Persistent installation
# - Optimal performance

Mixed Tool Management

DON'T:

# BAD: Mixing pip and uv tool
pip install --user black
uv tool install flake8
pipx install pytest
# Problems:
# - Inconsistent management
# - Difficult to track
# - Potential conflicts
# - Hard to maintain

DO:

# GOOD: Use UV tool exclusively
uv tool install black
uv tool install flake8
uv tool install pytest
# Benefits:
# - Consistent management
# - Easy to track
# - No conflicts
# - Simple maintenance

Forgetting Virtual Environments

DON'T:

# BAD: Installing packages globally
cd my-project
uv pip install requests  # Installs to global Python
# Problems:
# - Pollutes global environment
# - Version conflicts
# - Difficult to reproduce
# - No isolation

DO:

# GOOD: Always use virtual environments
cd my-project
python -m venv .venv
. .venv/Scripts/activate
uv pip install requests
# Benefits:
# - Project isolation
# - Clean environments
# - Easy reproduction
# - No global pollution

Related Documentation

• Tool Management Reference
• MCP Integration
• Python Environment Management

CI/CD Examples

Overview

Continuous integration and deployment configurations with UV.

GitHub Actions

name: Python Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.10', '3.11', '3.12']

    steps:
      - uses: actions/checkout@v4

      - name: Setup UV
        uses: astral-sh/setup-uv@v1

      - name: Install Python
        run: uv python install ${{ matrix.python-version }}

      - name: Create virtual environment
        run: uv venv

      - name: Install dependencies
        run: uv pip install -r requirements.txt

      - name: Install development tools
        run: |
          uv tool install black
          uv tool install flake8
          uv tool install pytest

      - name: Format check
        run: black --check .

      - name: Lint
        run: flake8 .

      - name: Test
        run: pytest tests/

GitLab CI

stages:
  - test
  - lint
  - deploy

test:
  stage: test
  image: python:3.12
  before_script:
    - curl -LsSf https://astral.sh/uv/install.sh | sh
    - export PATH="$HOME/.local/bin:$PATH"
    - uv venv
    - source .venv/bin/activate
  script:
    - uv pip install -r requirements.txt
    - uv tool install pytest
    - pytest tests/

lint:
  stage: lint
  image: python:3.12
  before_script:
    - curl -LsSf https://astral.sh/uv/install.sh | sh
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - uv tool install black
    - uv tool install flake8
    - black --check .
    - flake8 .

deploy:
  stage: deploy
  image: python:3.12
  only:
    - main
  script:
    - curl -LsSf https://astral.sh/uv/install.sh | sh
    - export PATH="$HOME/.local/bin:$PATH"
    - uv build
    - uv publish

Related Documentation

• Installation and Setup Reference
• Tool Management
• Python Environment Management

Common Patterns

Overview

Frequently used patterns and configurations for UV development.

Development Tool Suite

# Install complete development suite
uv tool install black         # Code formatter
uv tool install flake8        # Linter
uv tool install mypy          # Type checker
uv tool install pytest        # Testing
uv tool install coverage      # Coverage
uv tool install pre-commit    # Git hooks
uv tool install commitizen    # Commit conventions
uv tool install cookiecutter  # Project templates

# Verify installations
uv tool list

# Weekly maintenance
uv tool upgrade --all
uv cache clean

Pre-commit Integration

.pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: black
        name: Format with black
        entry: black
        language: system
        types: [python]

      - id: flake8
        name: Lint with flake8
        entry: flake8
        language: system
        types: [python]

      - id: mypy
        name: Type check with mypy
        entry: mypy
        language: system
        types: [python]

Setup:

# Install tools
uv tool install black flake8 mypy pre-commit

# Install hooks
pre-commit install

# Test hooks
pre-commit run --all-files

Shell Configuration

~/.bashrc or ~/.zshrc:

# UV aliases
alias uv-update='uv tool upgrade --all'
alias uv-clean='uv cache clean'

# Development aliases
alias fmt='black'
alias lint='flake8'
alias type='mypy'
alias test='pytest'

# Project shortcuts
alias venv-activate='. .venv/Scripts/activate'  # or source .venv/bin/activate
alias venv-create='python -m venv .venv'
alias deps-install='uv pip install -r requirements.txt'
alias deps-freeze='uv pip freeze > requirements.txt'

# Ensure UV tools in PATH
export PATH="$HOME/.local/bin:$PATH"

Related Documentation

• Tool Management Reference
• Installation and Setup
• Development Workflows

Complete Workflow Example

Overview

End-to-end example of setting up a new Python project with UV.

Setting Up a New Python Project

# 1. Create project directory
mkdir my-awesome-project
cd my-awesome-project

# 2. Initialize git
git init

# 3. Create .gitignore
cat > .gitignore << EOF
.venv/
__pycache__/
*.pyc
.pytest_cache/
.coverage
EOF

# 4. Create virtual environment
python -m venv .venv

# 5. Activate virtual environment
. .venv/Scripts/activate  # Windows Git Bash
# source .venv/bin/activate  # Linux/Mac

# 6. Install project dependencies
uv pip install requests fastapi uvicorn

# 7. Freeze dependencies
uv pip freeze > requirements.txt

# 8. Install development tools (globally with UV tool)
uv tool install black
uv tool install flake8
uv tool install mypy
uv tool install pytest

# 9. Create project structure
mkdir src tests
touch src/__init__.py
touch tests/__init__.py

# 10. Create main application
cat > src/main.py << EOF
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello World"}
EOF

# 11. Create test
cat > tests/test_main.py << EOF
from src.main import app
from fastapi.testclient import TestClient

client = TestClient(app)

def test_read_root():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello World"}
EOF

# 12. Format code
black .

# 13. Lint code
flake8 src/ tests/

# 14. Run tests
pytest tests/

# 15. Create README
cat > README.md << EOF
# My Awesome Project

## Setup

\`\`\`bash
python -m venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt
\`\`\`

## Run

\`\`\`bash
uvicorn src.main:app --reload
\`\`\`

## Test

\`\`\`bash
pytest tests/
\`\`\`
EOF

# 16. Commit
git add .
git commit -m "Initial project setup"

echo "Project setup complete!"

What This Workflow Demonstrates

• Complete project initialization from scratch
• Git repository setup with proper .gitignore
• Virtual environment creation and activation
• Dependency management with UV
• Development tool installation
• Project structure creation
• Application and test code creation
• Code formatting and linting
• Test execution
• Documentation creation
• Initial git commit

Related Documentation

• Installation and Setup Reference
• Tool Management
• Python Environment Management
• Virtual Environment Workflows
• Development Workflows

Development Tool Workflows

Overview

Complete development tool setup and daily workflow patterns with UV.

Python Development Environment

# One-time setup: Install development tools
uv tool install black
uv tool install flake8
uv tool install mypy
uv tool install pytest
uv tool install coverage

# Daily development workflow
# Format code
black .

# Lint code
flake8 src/

# Type check
mypy src/

# Run tests
pytest tests/

# Run with coverage
coverage run -m pytest
coverage report

Project-Specific Script Execution

# Project structure:
# my-project/
# ├── scripts/
# │   ├── setup_database.py
# │   ├── generate_docs.py
# │   └── deploy.py
# └── pyproject.toml

# Run scripts without installing globally
uvx --from . scripts/setup_database.py
uvx --from . scripts/generate_docs.py --format html
uvx --from . scripts/deploy.py --environment production

Multi-Version Testing

# Test code against multiple Python versions
uv python install 3.10 3.11 3.12

# Test with Python 3.10
uv python pin 3.10
uvx --from . tests/run_tests.py

# Test with Python 3.11
uv python pin 3.11
uvx --from . tests/run_tests.py

# Test with Python 3.12
uv python pin 3.12
uvx --from . tests/run_tests.py

# Compare results
diff <(uv run --python 3.10 tests/test.py) \
     <(uv run --python 3.12 tests/test.py)

Related Documentation

• Tool Management Reference
• Python Environment Management
• Installation and Setup

Inline Script Metadata (PEP 723)

Overview

UV supports inline script metadata, allowing you to define dependencies directly in Python script comments. UV automatically installs these dependencies when running the script.

Basic Inline Dependencies

# /// script
# dependencies = [
#   "requests",
#   "pandas",
#   "numpy",
# ]
# ///

import requests
import pandas as pd
import numpy as np

def main():
    response = requests.get("https://api.example.com/data")
    df = pd.DataFrame(response.json())
    print(df.describe())

if __name__ == "__main__":
    main()

Run with UV:

# UV automatically installs dependencies and runs the script
uv run script.py

# Or with uvx
uvx script.py

With Python Version Requirement

# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "fastapi>=0.100.0",
#   "uvicorn[standard]>=0.24.0",
# ]
# ///

from fastapi import FastAPI
import uvicorn

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello World"}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

Run with specific Python version:

uv run --python 3.11 server.py

MCP Server with Inline Dependencies

# /// script
# dependencies = [
#   "mcp>=0.1.0",
#   "anthropic-sdk>=0.3.0",
# ]
# ///

from mcp.server import Server
from mcp.types import Tool

server = Server("my-mcp-server")

@server.list_tools()
async def list_tools():
    return [
        Tool(name="echo", description="Echo a message", input_schema={})
    ]

if __name__ == "__main__":
    server.run()

VS Code Configuration:

{
  "mcpServers": {
    "my-server": {
      "command": "uv",
      "args": ["run", "/path/to/server.py"]
    }
  }
}

Data Processing Script

# /// script
# requires-python = ">=3.10"
# dependencies = [
#   "polars>=0.19.0",
#   "matplotlib>=3.8.0",
#   "seaborn>=0.12.0",
# ]
# ///

import polars as pl
import matplotlib.pyplot as plt
import seaborn as sns

def analyze_data(file_path: str):
    # Read data with polars (faster than pandas)
    df = pl.read_csv(file_path)

    # Perform analysis
    summary = df.describe()
    print(summary)

    # Create visualization
    sns.histplot(df.to_pandas()["column_name"])
    plt.savefig("output.png")

if __name__ == "__main__":
    import sys
    analyze_data(sys.argv[1])

Usage:

# UV installs polars, matplotlib, seaborn automatically
uv run analyze.py data.csv

Benefits of Inline Script Metadata

1. Self-contained scripts - Dependencies travel with the script 2. No pyproject.toml needed - Perfect for single-file scripts 3. Automatic dependency management - UV handles installation 4. Version control friendly - Everything in one file 5. Easy sharing - Send script, UV handles the rest

When to Use Inline Metadata

DO use for:

• Single-file utility scripts
• Data analysis notebooks converted to scripts
• Quick automation tasks
• Shareable examples and demos
• Scripts without full project structure

DON'T use for:

• Multi-file projects (use pyproject.toml instead)
• Scripts with many dependencies (harder to read)
• Production applications (use proper project structure)
• Scripts that need development dependencies separately

Related Documentation

• Inline Script Metadata Reference
• Python Environment Management
• MCP Integration

MCP Server Examples

Overview

Complete MCP server configuration examples for various platforms and use cases.

Published MCP Servers

Official MCP Servers Repository

From: github.com/modelcontextprotocol/servers

{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/path/to/repo"]
    },
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "/path/to/database.db"]
    },
    "filesystem": {
      "command": "uvx",
      "args": [
        "mcp-server-filesystem",
        "/allowed/path1",
        "/allowed/path2"
      ]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

AWS MCP Servers

From: github.com/awslabs/mcp

{
  "mcpServers": {
    "core": {
      "command": "uvx",
      "args": ["awslabs.core-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    },
    "lambda": {
      "command": "uvx",
      "args": ["awslabs.lambda-mcp-server@latest"],
      "env": {
        "AWS_REGION": "us-east-1"
      }
    },
    "bedrock": {
      "command": "uvx",
      "args": ["awslabs.bedrock-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "default"
      }
    },
    "nova-canvas": {
      "command": "uvx",
      "args": ["awslabs.nova-canvas-mcp-server@latest"]
    }
  }
}

VS Code MCP Documentation

From: code.visualstudio.com/docs/copilot/chat/mcp-servers

{
  "servers": {
    "fetch": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

Continue IDE

From: Continue IDE Documentation

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": ["mcp-server-sqlite", "--db-path", "/Users/NAME/test.db"]
        }
      },
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": ["mcp-server-fetch"]
        }
      }
    ]
  }
}

Local MCP Server Development

Basic Local Development

{
  "mcpServers": {
    "sql-plugins": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "d:/mcp/my.python/sqlplugins",
        "mcp_server.py",
        "--env", "d:/mcp/my.python/sqlplugins/hr2.env"
      ]
    }
  }
}

Development with Multiple Configurations

{
  "mcpServers": {
    "dev-server": {
      "command": "uvx",
      "args": [
        "--from", "${workspaceFolder}",
        "src/server.py",
        "--debug"
      ]
    },
    "test-server": {
      "command": "uvx",
      "args": [
        "--from", "${workspaceFolder}",
        "src/server.py",
        "--config", "test_config.json"
      ]
    },
    "prod-server": {
      "command": "uvx",
      "args": ["my-mcp-server@1.0.0"]
    }
  }
}

Related Documentation

• MCP Integration Reference
• Inline Script Metadata
• Installation and Setup

Migration Examples

Overview

Migration guides from other Python tools to UV.

From pip to UV

Before (pip):

# Old workflow
pip install requests pandas numpy
pip freeze > requirements.txt

# Problems:
# - Slow installation
# - Dependency conflicts
# - No isolation

After (UV):

# New workflow
python -m venv .venv
. .venv/Scripts/activate
uv pip install requests pandas numpy
uv pip freeze > requirements.txt

# Benefits:
# - 10-100x faster
# - Better dependency resolution
# - Virtual environment isolation

From pipx to UV tool

Before (pipx):

# Old tool management
pipx install black
pipx install flake8
pipx install pytest
pipx upgrade-all

After (UV tool):

# New tool management
uv tool install black
uv tool install flake8
uv tool install pytest
uv tool upgrade --all

# Migration:
pipx list --short > tools.txt
cat tools.txt | xargs -n1 uv tool install

From poetry to UV

Before (poetry):

# Old project management
poetry new my-project
cd my-project
poetry add requests
poetry install
poetry run python script.py

After (UV):

# New project management
uv init my-project
cd my-project
uv add requests
uv sync
uv run python script.py

# Migration from existing poetry project:
poetry export -f requirements.txt -o requirements.txt
python -m venv .venv
. .venv/Scripts/activate
uv pip install -r requirements.txt

Related Documentation

• Installation and Setup Reference
• Tool Management
• Python Environment Management

UV Real-World Examples

Overview

This directory contains real-world examples, common patterns, and anti-patterns for UV usage across different scenarios.

Example Categories

Inline Script Metadata

PEP 723 inline script metadata examples with UV. Learn how to create self-contained Python scripts with embedded dependencies.

Topics:

• Basic inline dependencies
• Python version requirements
• MCP server with inline dependencies
• Data processing scripts
• When to use inline metadata

MCP Server Examples

Complete MCP server configuration examples for various platforms and use cases.

Topics:

• Published MCP servers (official, AWS, etc.)
• VS Code and Continue IDE configurations
• Local development setup
• Multi-configuration development

Development Workflows

Complete development tool setup and daily workflow patterns.

Topics:

• Python development environment setup
• Project-specific script execution
• Multi-version testing workflows

Virtual Environment Workflows

Virtual environment management patterns and best practices.

Topics:

• Basic project setup
• Existing project migration
• Multi-environment projects

CI/CD Examples

Continuous integration and deployment configurations.

Topics:

• GitHub Actions workflows
• GitLab CI pipelines

Migration Examples

Migration guides from other Python tools to UV.

Topics:

• From pip to UV
• From pipx to UV tool
• From poetry to UV

Common Patterns

Frequently used patterns and configurations.

Topics:

• Development tool suite setup
• Pre-commit integration
• Shell configuration

Anti-Patterns

Common mistakes to avoid when using UV.

Topics:

• Global pip installs
• Installing MCP servers with uv tool
• Using uvx for daily tools
• Mixed tool management
• Forgetting virtual environments

Complete Workflow

End-to-end example of setting up a new Python project with UV.

Topics:

• Full project initialization
• Git setup
• Dependency management
• Testing and formatting
• Documentation

How to Use These Examples

1. Browse by topic - Use the category links above to find relevant examples 2. Copy and adapt - All examples are designed to be copied and modified for your needs 3. Follow patterns - Use the "DO" examples and avoid the "DON'T" anti-patterns 4. Refer to related docs - Each example file links to relevant reference documentation

Related Documentation

• Installation and Setup
• Tool Management
• Python Environment Management
• Inline Script Metadata
• MCP Integration

Virtual Environment Workflows

Overview

Virtual environment management patterns and best practices with UV.

Basic Project Setup

# Create new project directory
mkdir my-project
cd my-project

# Create virtual environment
python -m venv .venv

# Activate (Windows Git Bash)
. .venv/Scripts/activate

# Activate (Linux/Mac)
source .venv/bin/activate

# Install dependencies with UV
uv pip install requests pandas numpy

# Freeze dependencies
uv pip freeze > requirements.txt

# Deactivate when done
deactivate

Existing Project Migration

# Clone existing project
git clone https://github.com/user/project.git
cd project

# Create virtual environment
python -m venv .venv

# Activate
. .venv/Scripts/activate  # Windows Git Bash
source .venv/bin/activate  # Linux/Mac

# Install from requirements with UV (much faster than pip)
uv pip install -r requirements.txt

# Verify installation
python -c "import requests; print('Success!')"

Multi-Environment Project

# Development environment
python -m venv .venv-dev
. .venv-dev/Scripts/activate
uv pip install -r requirements-dev.txt
deactivate

# Production environment
python -m venv .venv-prod
. .venv-prod/Scripts/activate
uv pip install -r requirements.txt
deactivate

# Testing environment
python -m venv .venv-test
. .venv-test/Scripts/activate
uv pip install -r requirements.txt pytest coverage
deactivate

# Use specific environment
. .venv-test/Scripts/activate
pytest tests/

Related Documentation

• Python Environment Management Reference
• Installation and Setup
• Tool Management

UV Skill for Claude Code

A comprehensive skill for working with UV, the extremely fast Python package and project manager. This skill provides guidance on Python environment management, MCP server integration, and modern Python development workflows.

Stay Current: This skill is aware of recent UV changes including Python 3.14 default, free-threaded Python support, and new features in UV 0.9.6+.

Overview

UV is a Rust-powered Python package manager that replaces pip, pipx, poetry, pyenv, and more - delivering 10-100x faster performance. This skill helps Claude Code users:

• Set up and manage Python virtual environments
• Install and manage Python CLI tools efficiently
• Run MCP (Model Context Protocol) servers with UVX
• Configure VS Code and other IDEs for MCP integration
• Migrate from pip, pipx, or poetry to UV
• Stay current with latest UV features and version-specific changes
• Troubleshoot UV-related issues

Features

• Version-Aware Guidance - Tracks recent UV changes (0.9.6+) including Python 3.14 default and free-threaded Python
• Complete UV Command Reference - Coverage of uv pip, uv tool, uvx, uv venv, and uv python
• Inline Script Metadata (PEP 723) - Single-file scripts with dependencies in comments
• MCP Server Integration - Detailed patterns for both published packages and local development
• Cross-Platform Support - Instructions for Windows, Linux, and macOS
• Real-World Examples - GitHub Actions, VS Code, Continue IDE configurations
• Migration Guides - Step-by-step migration from pip, pipx, and poetry
• Performance Insights - Understanding UV's 10-100x speed improvements
• Troubleshooting - Common issues and solutions

Installation

Install the Skill

Copy the skill to your Claude Code skills directory:

Windows (Git Bash):

cp -r . "$USERPROFILE/.claude/skills/uv"

Linux/macOS:

cp -r . ~/.claude/skills/uv

Verify Installation

Ask Claude Code: "How do I install UV?" or "Help me set up a Python virtual environment with UV"

Claude should activate this skill and provide UV-specific guidance.

Skill Structure

uv-skill/
├── SKILL.md                          # Main skill file with core UV concepts
├── references/
│   ├── recent-changes.md             # Latest UV version changes (0.9.6+)
│   ├── installation-and-setup.md     # Installation and virtual environment setup
│   ├── tool-management.md            # UV tool install vs uvx comparison
│   ├── mcp-integration.md            # MCP server execution patterns
│   ├── python-environment.md         # Python version management
│   ├── inline-script-metadata.md     # PEP 723 inline dependencies
│   └── examples.md                   # Real-world configurations
├── docs/
│   └── guides/
│       └── testing-the-uv-skill.md   # Testing framework with test cases
├── README.md                         # This file
├── VERSION                           # Current version
└── LICENSE                           # MIT License

When Claude Uses This Skill

Claude will automatically activate this skill when you:

• Ask about UV or UVX
• Need to install or manage Python packages
• Want to set up virtual environments
• Work with MCP servers
• Ask about Python tool management
• Need help migrating from pip, pipx, or poetry
• Troubleshoot UV-related errors

Quick Start Examples

Ask Claude

Version & Recent Changes:

• "What version of UV should I be using?"
• "What's new in UV 0.9.6?"
• "How do I use free-threaded Python with UV?"
• "What Python version will UV install by default?"

Virtual Environments:

• "How do I create a Python virtual environment with UV?"
• "Help me activate my venv and install packages using UV"

Tool Management:

• "Should I use uv tool install or uvx for black?"
• "How do I install development tools with UV?"

MCP Servers:

• "How do I run mcp-server-sqlite with uvx?"
• "Configure VS Code to use uvx for MCP servers"
• "How do I run a local MCP server with uvx --from?"

Migration:

• "Help me migrate from pip to UV"
• "Convert my pipx installations to UV tool"

Troubleshooting:

• "I'm getting spawn uvx ENOENT error"
• "UV can't find my package"

What's Included

Core Concepts (SKILL.md)

• UV command overview (uv pip, uv tool, uvx, uv venv, uv python)
• Tool vs UVX decision tree
• MCP server execution patterns
• Virtual environment management
• Common workflows and integration patterns
• Best practices and anti-patterns

Reference Documentation

1. Recent Changes - Latest UV version information (0.9.6+), Python 3.14 default, free-threaded Python, new features 2. Installation & Setup - Cross-platform installation, virtual environment setup 3. Tool Management - Persistent vs temporary execution, maintenance workflows 4. MCP Integration - Published packages, local development, IDE configuration 5. Python Environment - Version management, cross-platform paths 6. Inline Script Metadata - PEP 723 dependencies in comments, single-file scripts 7. Examples - Real-world GitHub configurations, workflow patterns

Recent Changes Awareness

This skill stays current with the latest UV developments. Claude Code will be aware of:

UV 0.9.6+ Features

• Python 3.14 Default - UV now installs Python 3.14 by default (previously 3.13)
• Free-Threaded Python - Python 3.14+ without GIL for true parallel execution
• Build --clear Flag - Automatic cleanup of old build artifacts with uv build --clear

UV 0.9.7 Features

• Security Updates - Improved tar/ZIP archive handling
• Windows x86-32 Support - Better compatibility on Windows systems

Version-Aware Guidance

Claude Code will:

• Recommend upgrading if your UV version lacks needed features
• Provide version-specific instructions
• Warn about deprecated features
• Explain breaking changes and migration paths

Ask questions like:

• "What Python version will UV install by default?"
• "How do I use free-threaded Python with UV?"
• "Do I need to upgrade UV for Python 3.14?"
• "What's new in UV 0.9.6?"

Key Concepts

UV Commands

Tool vs UVX Decision

• Use `uv tool install` for: black, flake8, mypy, pytest (daily tools)
• Use `uvx` for: MCP servers, one-off executions, testing

MCP Server Patterns

• Published packages: uvx mcp-server-sqlite --db-path /path/to/db
• Local development: uvx --from /path/to/project server.py

Best Practices

DO

• Use python -m venv for project virtual environments
• Use uv tool install for frequently used development tools
• Use uvx for all MCP server execution
• Use --from flag for local MCP server development
• Pin versions in production (package@1.2.3)

DON'T

• Install packages globally without virtual environments
• Mix pip and uv tool installations
• Install MCP servers with uv tool install
• Use uvx for daily development tools
• Use @latest in production

Performance

UV delivers exceptional performance:

• 10-100x faster than pip for package operations
• Parallel downloads and installations
• Global cache with deduplication
• Rust-powered dependency resolution
• Sub-second virtual environment creation

Troubleshooting

Common issues covered:

• "spawn uvx ENOENT" errors (PATH issues)
• Package not found (PyPI vs local)
• Permission errors (cache directory)
• Version conflicts (Python versions)

See detailed troubleshooting in reference documentation.

Development

Testing the Skill Locally

1. Copy skill to Claude skills directory 2. Restart Claude Code (if needed) 3. Ask UV-related questions 4. Verify Claude activates the skill 5. Check responses match documentation

Updating the Skill

1. Edit SKILL.md or reference files 2. Test changes locally 3. Update VERSION file 4. Commit and push changes

Version History

• 0.1.0 - Initial release
• Complete UV command reference
• Version-aware guidance for UV 0.9.6+ features
• Python 3.14 default version documentation
• Free-threaded Python support (PEP 703)
• New uv build --clear flag documentation
• Security updates awareness (tar/ZIP handling)
• MCP server integration patterns
• Cross-platform installation guides
• Migration guides from pip/pipx/poetry
• Real-world examples and configurations
• Enhanced testing guide with version-specific test cases
• Comprehensive version compatibility matrix

Contributing

Contributions welcome! Areas for improvement:

• Additional real-world examples
• More troubleshooting scenarios
• Integration patterns for other IDEs
• Performance benchmarks
• Platform-specific optimizations

Resources

Official Documentation

• UV Official Docs
• UV GitHub Repository
• MCP Official Documentation
• MCP Servers Repository
• VS Code MCP Support

Claude Code

• Claude Code Skills Documentation
• Skill Best Practices

License

MIT License - See LICENSE file

Support

For issues or questions:

• Check the reference documentation in references/
• Ask Claude Code using this skill
• Review troubleshooting sections
• Consult official UV documentation

Acknowledgments

This skill is based on:

• Official UV documentation and community practices
• Real-world MCP server integration patterns
• Claude Code skill best practices
• Community feedback and testing

UV Inline Script Metadata Reference (PEP 723)

Overview

UV supports PEP 723 inline script metadata, allowing you to define dependencies directly in Python script comments. This eliminates the need for separate pyproject.toml files for single-file scripts and enables self-contained, shareable Python scripts.

What is Inline Script Metadata?

Inline script metadata is a standardized way (PEP 723) to embed dependency information directly in Python script comments. UV reads these metadata blocks and automatically manages dependencies when running the script.

Basic Syntax

# /// script
# dependencies = [
#   "package-name",
#   "another-package>=1.0.0",
# ]
# requires-python = ">=3.10"
# ///

# Your Python code here

Key Elements:

• # /// script - Opening marker (must be exact)
• # dependencies = [...] - List of package dependencies
• # requires-python = "..." - Optional Python version constraint
• # /// - Closing marker (must be exact)

Important: The markers # /// script and # /// must be on their own lines with exact spacing.

Basic Examples

Simple Script with Dependencies

# /// script
# dependencies = [
#   "requests",
#   "beautifulsoup4",
# ]
# ///

import requests
from bs4 import BeautifulSoup

def scrape_website(url):
    response = requests.get(url)
    soup = BeautifulSoup(response.content, 'html.parser')
    return soup.title.string

if __name__ == "__main__":
    title = scrape_website("https://example.com")
    print(f"Page title: {title}")

Run with UV:

# UV automatically installs requests and beautifulsoup4
uv run scraper.py

With Specific Versions

# /// script
# dependencies = [
#   "requests>=2.28.0,<3.0.0",
#   "pandas==2.1.0",
#   "numpy>=1.24.0",
# ]
# requires-python = ">=3.10"
# ///

import pandas as pd
import numpy as np
import requests

def fetch_and_analyze(api_url):
    response = requests.get(api_url)
    data = response.json()
    df = pd.DataFrame(data)
    return df.describe()

if __name__ == "__main__":
    stats = fetch_and_analyze("https://api.example.com/data")
    print(stats)

Run with UV:

# UV ensures Python 3.10+ and specific package versions
uv run analysis.py

Data Processing Examples

Polars Data Analysis

# /// script
# requires-python = ">=3.10"
# dependencies = [
#   "polars>=0.19.0",
#   "matplotlib>=3.8.0",
#   "seaborn>=0.12.0",
# ]
# ///

import polars as pl
import matplotlib.pyplot as plt
import seaborn as sns
import sys

def analyze_csv(file_path: str):
    # Read data with polars (faster than pandas)
    df = pl.read_csv(file_path)

    # Print summary statistics
    print(df.describe())

    # Create visualization
    plt.figure(figsize=(10, 6))
    data_pandas = df.to_pandas()
    sns.histplot(data=data_pandas, x="column_name", bins=30)
    plt.title("Data Distribution")
    plt.savefig("distribution.png")
    print("Saved visualization to distribution.png")

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python analyze.py <file.csv>")
        sys.exit(1)
    analyze_csv(sys.argv[1])

Usage:

uv run analyze.py data.csv

Excel Processing

# /// script
# dependencies = [
#   "openpyxl>=3.1.0",
#   "pandas>=2.0.0",
# ]
# ///

import pandas as pd
import sys

def process_excel(input_file: str, output_file: str):
    # Read Excel file
    df = pd.read_excel(input_file)

    # Perform transformations
    df['total'] = df['quantity'] * df['price']
    summary = df.groupby('category')['total'].sum()

    # Write to new Excel file
    with pd.ExcelWriter(output_file, engine='openpyxl') as writer:
        df.to_excel(writer, sheet_name='Data', index=False)
        summary.to_excel(writer, sheet_name='Summary')

    print(f"Processed data saved to {output_file}")

if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("Usage: python process.py input.xlsx output.xlsx")
        sys.exit(1)
    process_excel(sys.argv[1], sys.argv[2])

Usage:

uv run process.py input.xlsx output.xlsx

Web Application Examples

FastAPI Server

# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "fastapi>=0.100.0",
#   "uvicorn[standard]>=0.24.0",
# ]
# ///

from fastapi import FastAPI
import uvicorn

app = FastAPI(title="Simple API")

@app.get("/")
def read_root():
    return {"message": "Hello World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "query": q}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

Run server:

uv run server.py
# Visit http://localhost:8000

Flask Application

# /// script
# dependencies = [
#   "flask>=3.0.0",
#   "flask-cors>=4.0.0",
# ]
# ///

from flask import Flask, jsonify, request
from flask_cors import CORS

app = Flask(__name__)
CORS(app)

@app.route('/')
def home():
    return jsonify({"message": "Welcome to Flask API"})

@app.route('/data', methods=['GET', 'POST'])
def handle_data():
    if request.method == 'POST':
        data = request.json
        return jsonify({"received": data}), 201
    else:
        return jsonify({"data": ["item1", "item2", "item3"]})

if __name__ == '__main__':
    app.run(debug=True, port=5000)

Run server:

uv run app.py

MCP Server Examples

Basic MCP Server

# /// script
# dependencies = [
#   "mcp>=0.1.0",
# ]
# ///

from mcp.server import Server
from mcp.types import Tool, TextContent

server = Server("example-server")

@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="greet",
            description="Greet someone by name",
            input_schema={
                "type": "object",
                "properties": {
                    "name": {"type": "string"}
                },
                "required": ["name"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "greet":
        person_name = arguments.get("name", "World")
        return [TextContent(
            type="text",
            text=f"Hello, {person_name}!"
        )]

if __name__ == "__main__":
    import asyncio
    asyncio.run(server.run())

VS Code Configuration:

{
  "mcpServers": {
    "example": {
      "command": "uv",
      "args": ["run", "/path/to/mcp_server.py"]
    }
  }
}

MCP Server with Database

# /// script
# dependencies = [
#   "mcp>=0.1.0",
#   "aiosqlite>=0.19.0",
# ]
# ///

from mcp.server import Server
from mcp.types import Tool, TextContent
import aiosqlite
import os

server = Server("database-server")
DB_PATH = os.getenv("DB_PATH", "data.db")

@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="query_db",
            description="Execute SQL query",
            input_schema={
                "type": "object",
                "properties": {
                    "query": {"type": "string"}
                },
                "required": ["query"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "query_db":
        query = arguments.get("query")
        async with aiosqlite.connect(DB_PATH) as db:
            cursor = await db.execute(query)
            results = await cursor.fetchall()
            return [TextContent(
                type="text",
                text=str(results)
            )]

if __name__ == "__main__":
    import asyncio
    asyncio.run(server.run())

VS Code Configuration with Environment:

{
  "mcpServers": {
    "database": {
      "command": "uv",
      "args": ["run", "/path/to/db_server.py"],
      "env": {
        "DB_PATH": "/path/to/database.db"
      }
    }
  }
}

Automation and CLI Tools

File Processor

# /// script
# dependencies = [
#   "typer>=0.9.0",
#   "rich>=13.0.0",
# ]
# ///

import typer
from rich.console import Console
from pathlib import Path

app = typer.Typer()
console = Console()

@app.command()
def process(
    input_dir: Path = typer.Argument(..., help="Input directory"),
    output_dir: Path = typer.Argument(..., help="Output directory"),
    pattern: str = typer.Option("*.txt", help="File pattern to match")
):
    """Process files matching pattern from input to output directory."""
    files = list(input_dir.glob(pattern))

    with console.status(f"Processing {len(files)} files..."):
        for file in files:
            # Your processing logic here
            output_path = output_dir / file.name
            output_path.write_text(file.read_text().upper())

    console.print(f"[green]✓[/green] Processed {len(files)} files")

if __name__ == "__main__":
    app()

Usage:

uv run processor.py input/ output/ --pattern "*.txt"

AWS Resource Lister

# /// script
# requires-python = ">=3.10"
# dependencies = [
#   "boto3>=1.28.0",
#   "rich>=13.0.0",
# ]
# ///

import boto3
from rich.console import Console
from rich.table import Table

def list_s3_buckets():
    s3 = boto3.client('s3')
    response = s3.list_buckets()

    console = Console()
    table = Table(title="S3 Buckets")
    table.add_column("Name", style="cyan")
    table.add_column("Creation Date", style="magenta")

    for bucket in response['Buckets']:
        table.add_row(
            bucket['Name'],
            bucket['CreationDate'].strftime('%Y-%m-%d %H:%M:%S')
        )

    console.print(table)

if __name__ == "__main__":
    list_s3_buckets()

Usage:

# Assumes AWS credentials are configured
uv run list_buckets.py

Running Inline Scripts

Basic Execution

# UV installs dependencies and runs the script
uv run script.py

# With arguments
uv run script.py arg1 arg2 --flag

# With specific Python version
uv run --python 3.11 script.py

Using uvx

# Run from any location
uvx /path/to/script.py

# With arguments
uvx script.py --input data.csv --output results.csv

In IDE Configurations

VS Code tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run Script with UV",
      "type": "shell",
      "command": "uv",
      "args": ["run", "${file}"],
      "group": {
        "kind": "build",
        "isDefault": true
      }
    }
  ]
}

VS Code launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "UV Run",
      "type": "python",
      "request": "launch",
      "module": "uv",
      "args": ["run", "${file}"]
    }
  ]
}

Best Practices

When to Use Inline Script Metadata

DO use for:

• Single-file utility scripts
• Quick automation tasks
• Data analysis scripts
• Shareable examples and demos
• Scripts without complex project structure
• CLI tools that fit in one file
• Learning and experimentation

DON'T use for:

• Multi-file projects (use pyproject.toml instead)
• Applications with many dependencies (>10-15 packages)
• Projects requiring separate dev/test dependencies
• Production applications with complex deployment
• Scripts that need package extras or complex configurations

Dependency Management

Prefer specific versions for reproducibility:

# Good - reproducible
# dependencies = [
#   "requests==2.31.0",
#   "pandas==2.1.0",
# ]

Use version ranges for flexibility:

# Good for utilities - allows newer compatible versions
# dependencies = [
#   "requests>=2.28.0,<3.0.0",
#   "pandas>=2.0.0",
# ]

Avoid unpinned versions in production:

# Risky - behavior can change unexpectedly
# dependencies = [
#   "requests",
#   "pandas",
# ]

Python Version Constraints

# Require minimum Python version
# requires-python = ">=3.10"

# Require specific version range
# requires-python = ">=3.10,<3.13"

# Require exact version (rarely needed)
# requires-python = "==3.11"

Organizing Dependencies

Alphabetical order for readability:

# /// script
# dependencies = [
#   "aiohttp>=3.9.0",
#   "beautifulsoup4>=4.12.0",
#   "pandas>=2.0.0",
#   "requests>=2.28.0",
# ]
# ///

Group by purpose with comments:

# /// script
# dependencies = [
#   # Web scraping
#   "requests>=2.28.0",
#   "beautifulsoup4>=4.12.0",
#   # Data processing
#   "pandas>=2.0.0",
#   "numpy>=1.24.0",
#   # Visualization
#   "matplotlib>=3.8.0",
#   "seaborn>=0.12.0",
# ]
# ///

Performance Considerations

First Run

• UV downloads and installs all dependencies
• Creates isolated environment
• Caches packages for future use
• Typical time: 5-30 seconds depending on dependencies

Subsequent Runs

• UV uses cached packages
• Environment reused if dependencies unchanged
• Typical startup: <1 second

Cache Management

# Check UV cache size
du -sh ~/.cache/uv/  # Linux/Mac
dir /s %LOCALAPPDATA%\uv\cache  # Windows

# Clean UV cache
uv cache clean

Troubleshooting

Invalid Metadata Format

Error:

Failed to parse inline script metadata

Solution: Ensure exact syntax:

# /// script    <- Must be exactly "# /// script"
# dependencies = [
#   "package",  <- Proper TOML array format
# ]
# ///           <- Must be exactly "# ///"

Dependency Not Found

Error:

Package 'package-name' not found on PyPI

Solution:

• Verify package name on PyPI
• Check for typos in package name
• Ensure package is available on PyPI

Version Conflict

Error:

Unable to resolve dependencies

Solution:

• Check version constraints are compatible
• Loosen version requirements if too restrictive
• Remove version constraints to find compatible versions

Python Version Mismatch

Error:

Requires Python >=3.11 but found 3.10

Solution:

# Install required Python version
uv python install 3.11

# Run with specific version
uv run --python 3.11 script.py

Comparison with Other Approaches

vs pyproject.toml

Inline Script Metadata:

• ✅ Single file - easy to share
• ✅ No project structure needed
• ✅ Perfect for utilities
• ❌ Limited to one file
• ❌ No dev dependencies separation

pyproject.toml:

• ✅ Multi-file projects
• ✅ Separate dev dependencies
• ✅ More configuration options
• ❌ Requires project structure
• ❌ Multiple files to share

vs requirements.txt

Inline Script Metadata:

• ✅ Dependencies in same file as code
• ✅ UV manages everything automatically
• ✅ Version control friendly
• ✅ Self-documenting

requirements.txt:

• ✅ Separate from code
• ✅ Familiar to most Python developers
• ❌ Requires manual management
• ❌ Two files to maintain

vs Docker

Inline Script Metadata:

• ✅ No Docker required
• ✅ Faster startup
• ✅ Native Python execution
• ✅ Simpler for users

Docker:

• ✅ Complete environment isolation
• ✅ System dependencies included
• ✅ Cross-platform guaranteed
• ❌ Heavier weight
• ❌ Slower startup

Summary

Inline script metadata (PEP 723) is perfect for:

• Single-file scripts that need dependencies
• Quick utilities and automation tasks
• Shareable examples that "just work"
• Learning and experimentation
• CLI tools that fit in one file

Use uv run script.py and UV handles the rest - no virtual environments, no pip install, no project setup. Just write your script and run it.

For multi-file projects or complex applications, use traditional pyproject.toml instead.

UV Installation and Setup Reference

Overview

This reference covers UV installation across platforms and virtual environment setup, with special focus on Windows compatibility and best practices.

Installation

Windows

PowerShell (Recommended):

powershell -c "irm https://install.python-uv.org | iex"

Alternative Methods:

# Using installer script
Invoke-WebRequest -Uri https://install.astral.sh/uv -OutFile install.ps1
.\install.ps1

# Using pipx (if available)
pipx install uv

Linux

# Standalone installer (Recommended)
curl -LsSf https://install.python-uv.org | sh

# Using pipx
pipx install uv

# Manual download
curl -sSL https://install.astral.sh/uv | sh

macOS

# Homebrew (Recommended)
brew install astral-sh/tap/uv

# Standalone installer
curl -LsSf https://install.python-uv.org | sh

Verification

After installation, verify UV is working:

uv --version
uvx --version

# Should output version number (e.g., uv 0.7.8)

Virtual Environment Setup

Windows Git Bash (Recommended for Windows)

Status: TESTED - UV works perfectly with venv virtual environments

# 1. Create virtual environment
python -m venv .venv

# 2. Activate environment
. .venv/Scripts/activate

# 3. Use UV for package management
uv pip install -r requirements.txt

# 4. Verify environment is active
echo $VIRTUAL_ENV
# Output: /d/path/to/project/.venv

# 5. Install packages
uv pip install requests numpy pandas

Git Bash Activation Notes:

Both . and source work identically:

# These are equivalent:
. .venv/Scripts/activate         # Recommended (shorter, POSIX standard)
source .venv/Scripts/activate    # Also works

Windows CMD

# 1. Create virtual environment
python -m venv .venv

# 2. Activate environment
.venv\Scripts\activate.bat

# 3. Use UV for package management
uv pip install -r requirements.txt

Linux/macOS

# 1. Create virtual environment
python -m venv .venv

# 2. Activate environment
source .venv/bin/activate

# 3. Use UV for package management
uv pip install -r requirements.txt

Project Initialization

Method 1: UV Project Creation

# Create new project with UV
uv init my-project
cd my-project

# Project structure created:
# my-project/
# ├── .python-version
# ├── pyproject.toml
# ├── README.md
# └── src/
#     └── my_project/
#         └── __init__.py

# Add dependencies
uv add requests numpy

# Run project
uv run python src/my_project/main.py

Method 2: Manual Setup with Virtual Environment

# Create project directory
mkdir my-project
cd my-project

# Create virtual environment
python -m venv .venv

# Activate (Windows Git Bash)
. .venv/Scripts/activate

# Activate (Linux/Mac)
source .venv/bin/activate

# Create requirements.txt
cat > requirements.txt << EOF
requests
numpy
pandas
EOF

# Install dependencies
uv pip install -r requirements.txt

Method 3: Existing Project Migration

# Navigate to existing project
cd existing-project

# Create virtual environment
python -m venv .venv

# Activate environment
. .venv/Scripts/activate  # Windows Git Bash
source .venv/bin/activate  # Linux/Mac

# Install from existing requirements
uv pip install -r requirements.txt

# Or install from poetry/pipenv
uv pip install poetry
poetry export -f requirements.txt -o requirements.txt
uv pip install -r requirements.txt

Common UV Commands

Package Management

# Install single package
uv pip install requests

# Install from requirements file
uv pip install -r requirements.txt

# Install with version constraint
uv pip install "requests>=2.28.0"

# Install multiple packages
uv pip install requests numpy pandas

# Uninstall package
uv pip uninstall requests

# List installed packages
uv pip list

# Show package information
uv pip show requests

# Freeze dependencies
uv pip freeze > requirements.txt

Tool Management

# Install persistent CLI tool
uv tool install black

# List installed tools
uv tool list

# Upgrade tool
uv tool upgrade black

# Upgrade all tools
uv tool upgrade --all

# Uninstall tool
uv tool uninstall black

# Run tool temporarily with uvx
uvx black my_file.py

Python Version Management

# List available Python versions
uv python list

# List installed Python versions
uv python list --installed

# Install Python version
uv python install 3.12

# Install specific minor version
uv python install 3.12.1

# Pin Python version for project
uv python pin 3.12

# Show pinned version
cat .python-version

Testing Installation

Complete Verification Script

For Windows Git Bash:

#!/bin/bash

echo "=== UV Installation Test ==="

# Check UV version
echo "1. UV Version:"
uv --version

# Create test environment
echo "2. Creating test virtual environment..."
python -m venv test-venv

# Activate environment
echo "3. Activating environment..."
. test-venv/Scripts/activate

# Verify activation
echo "4. Virtual environment path:"
echo $VIRTUAL_ENV

# Install test package
echo "5. Installing test package with UV..."
uv pip install requests

# Verify installation
echo "6. Testing package import..."
python -c "import requests; print(f'Requests version: {requests.__version__}')"

# List packages
echo "7. Installed packages:"
uv pip list

# Cleanup
echo "8. Cleanup..."
deactivate
rm -rf test-venv

echo "=== Test Complete ==="

For Linux/macOS:

#!/bin/bash

echo "=== UV Installation Test ==="

# Check UV version
echo "1. UV Version:"
uv --version

# Create test environment
echo "2. Creating test virtual environment..."
python -m venv test-venv

# Activate environment
echo "3. Activating environment..."
source test-venv/bin/activate

# Verify activation
echo "4. Virtual environment path:"
echo $VIRTUAL_ENV

# Install test package
echo "5. Installing test package with UV..."
uv pip install requests

# Verify installation
echo "6. Testing package import..."
python -c "import requests; print(f'Requests version: {requests.__version__}')"

# List packages
echo "7. Installed packages:"
uv pip list

# Cleanup
echo "8. Cleanup..."
deactivate
rm -rf test-venv

echo "=== Test Complete ==="

Platform-Specific Considerations

Windows Cache and Environment

Path Separators:

• Use / or \\ in paths depending on context
• Git Bash accepts both Unix-style (/) and Windows-style (\\) paths
• CMD requires Windows-style paths (\\)

Virtual Environment Activation:

• Git Bash: . .venv/Scripts/activate
• CMD: .venv\Scripts\activate.bat
• PowerShell: .venv\Scripts\Activate.ps1

UV Cache Location:

%LOCALAPPDATA%\uv\cache\

Linux/macOS Cache and Environment

Virtual Environment Activation:

source .venv/bin/activate

UV Cache Location:

~/.cache/uv/

Permissions:

# If permission errors occur
chmod +x ~/.local/bin/uv
chmod +x ~/.local/bin/uvx

Troubleshooting

UV Not Found After Installation

Windows:

# Check if UV is in PATH
$env:PATH -split ';' | Select-String "uv"

# Add to PATH manually if needed
$env:PATH += ";$env:LOCALAPPDATA\Programs\uv"

Linux/macOS:

# Check if UV is in PATH
echo $PATH | tr ':' '\n' | grep uv

# Add to PATH in ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

# Reload shell configuration
source ~/.bashrc  # or source ~/.zshrc

Virtual Environment Not Activating

Symptoms:

• $VIRTUAL_ENV is empty
• Packages install to global Python

Solutions:

For Git Bash:

# Ensure using correct activation command
. .venv/Scripts/activate

# Check if activate script exists
ls .venv/Scripts/activate

# Recreate if missing
rm -rf .venv
python -m venv .venv

For CMD:

# Use .bat extension
.venv\Scripts\activate.bat

# Check script exists
dir .venv\Scripts\activate.bat

UV Pip Install Fails

Symptoms:

• "No virtual environment found"
• Packages install to wrong location

Solutions:

# Ensure virtual environment is activated
echo $VIRTUAL_ENV  # Should show path

# If not activated, activate it
. .venv/Scripts/activate  # Windows Git Bash
source .venv/bin/activate  # Linux/Mac

# Verify activation
which python  # Should point to .venv

# Then install
uv pip install package-name

Permission Errors

Windows:

# Run PowerShell as Administrator
# Then reinstall UV
powershell -c "irm https://install.python-uv.org | iex"

Linux/macOS:

# Check UV cache permissions
ls -la ~/.cache/uv/

# Fix permissions if needed
chmod -R u+w ~/.cache/uv/

# Or install with different permissions
curl -LsSf https://install.python-uv.org | sh

Slow Package Installation

Potential Causes:

• Network proxy issues
• Antivirus scanning
• Large package dependencies

Solutions:

# Clear UV cache
uv cache clean

# Use specific index
uv pip install --index-url https://pypi.org/simple package-name

# Check cache size
du -sh ~/.cache/uv/  # Linux/Mac
dir /s %LOCALAPPDATA%\uv\cache  # Windows

Performance Benefits

Tested Results (UV 0.7.8 + Python 3.13.0)

Package Installation Speed:

• 10-100x faster than standard pip
• Parallel downloads and installations
• Intelligent caching with deduplication

Example Comparison:

# Standard pip
time pip install pandas numpy scipy
# ~45 seconds

# UV
time uv pip install pandas numpy scipy
# ~2 seconds (after first download)

Benefits:

• UV automatically detects virtual environments
• Perfect environment isolation
• Same commands as pip (drop-in replacement)
• Superior dependency conflict resolution

Best Practices

Environment Management

1. Always use virtual environments for projects 2. Activate before installing packages 3. Use `python -m venv` for compatibility 4. Document activation in README.md

Package Management Best Practices

1. Use UV for all installs in virtual environments 2. Freeze dependencies regularly (uv pip freeze) 3. Keep requirements.txt updated 4. Test installations in fresh environments

Tool Management Best Practices

1. Install development tools with uv tool install 2. Use uvx for temporary executions 3. Upgrade tools regularly with uv tool upgrade --all 4. Keep tools isolated (don't use global pip)

Quick Reference Card

# Installation
curl -LsSf https://install.python-uv.org | sh  # Linux/Mac
powershell -c "irm https://install.python-uv.org | iex"  # Windows

# Virtual Environment
python -m venv .venv
. .venv/Scripts/activate  # Windows Git Bash
source .venv/bin/activate  # Linux/Mac

# Package Management
uv pip install package-name
uv pip install -r requirements.txt
uv pip list
uv pip freeze > requirements.txt

# Tool Management
uv tool install black
uvx black file.py

# Python Versions
uv python list
uv python install 3.12
uv python pin 3.12

Summary

UV provides fast, reliable Python package management across all platforms. The recommended workflow is:

1. Install UV once globally 2. Create virtual environments with python -m venv 3. Activate environments before work 4. Use UV for all package operations 5. Use UV tool/uvx for CLI utilities

This combination provides maximum compatibility, performance, and reliability.

Python Environment Management Reference

Overview

This reference covers Python version management with UV, including installation paths, version pinning, and cross-platform compatibility. It also covers integration with pyenv and system Python.

Python Installation Paths

UV Python Installations

UV stores managed Python installations in platform-specific locations:

Linux/macOS:

~/.local/share/uv/python/cpython-<version>-<platform>/bin/python3

Windows:

%LOCALAPPDATA%\uv\python\cpython-<version>-<platform>\python.exe

Example Paths:

Linux:

~/.local/share/uv/python/cpython-3.12.6-linux-x86_64-gnu/bin/python3
~/.local/share/uv/python/cpython-3.11.8-linux-x86_64-gnu/bin/python3

Windows:

C:\Users\username\AppData\Local\uv\python\cpython-3.12.6-windows-x86_64\python.exe
C:\Users\username\AppData\Local\uv\python\cpython-3.11.8-windows-x86_64\python.exe

macOS:

~/.local/share/uv/python/cpython-3.12.6-macos-aarch64/bin/python3
~/.local/share/uv/python/cpython-3.12.6-macos-x86_64/bin/python3

Pyenv Python Installations

Pyenv stores Python installations in:

Linux/macOS:

~/.pyenv/versions/<version>/bin/python

Windows (pyenv-win):

%USERPROFILE%\.pyenv\pyenv-win\versions\<version>\python.exe

Example Paths:

~/.pyenv/versions/3.12.4/bin/python3.12
~/.pyenv/versions/3.11.8/bin/python3.11
~/.pyenv/versions/3.10.13/bin/python3.10

System Python

System Python locations vary by platform:

Linux (Debian/Ubuntu):

/usr/bin/python3
/usr/bin/python3.8
/usr/bin/python3.10

Linux (Fedora/RHEL):

/usr/bin/python3
/usr/bin/python3.9

macOS:

/usr/bin/python3
/Library/Frameworks/Python.framework/Versions/3.x/bin/python3

Windows:

C:\Python311\python.exe
C:\Program Files\Python311\python.exe

UV Python Version Management

Installation Commands

# Install latest Python version
uv python install

# Install specific version
uv python install 3.12

# Install specific patch version
uv python install 3.12.6

# Install multiple versions
uv python install 3.11 3.12 3.13

# Install from version file
uv python install --from-version-file .python-version

Listing Python Versions

# List all available Python versions
uv python list

# List only installed versions
uv python list --installed

# List with detailed information
uv python list --all-versions

Finding Python Paths

# Find path to specific Python version
uv python find 3.12

# Find path to specific patch version
uv python find 3.12.6

# Find path and show details
uv python find 3.12 --verbose

Version Pinning

# Pin Python version for project
uv python pin 3.12

# Pin specific patch version
uv python pin 3.12.6

# Creates .python-version file:
# 3.12.6

# Use pinned version
uv run python script.py  # Uses version from .python-version

Environment Variables

# Set custom Python installation directory
export UV_PYTHON_INSTALL_DIR=/custom/path/to/pythons

# On Windows
set UV_PYTHON_INSTALL_DIR=C:\custom\path\to\pythons

Direct Path Execution

Using Direct Paths

When shell wrappers (like pyenv) aren't available, use direct paths:

UV Python:

# Linux/macOS
~/.local/share/uv/python/cpython-3.12.6-linux-x86_64-gnu/bin/python3 script.py

# Windows
%LOCALAPPDATA%\uv\python\cpython-3.12.6-windows-x86_64\python.exe script.py

Pyenv Python:

# Linux/macOS
~/.pyenv/versions/3.12.4/bin/python3.12 script.py

# Windows (pyenv-win)
%USERPROFILE%\.pyenv\pyenv-win\versions\3.12.4\python.exe script.py

System Python:

# Linux
/usr/bin/python3.10 script.py

# Windows
C:\Python311\python.exe script.py

With Working Directories

# Change directory then execute
cd /path/to/working/directory && ~/.pyenv/versions/3.12.4/bin/python3.12 script.py

# Using UV run with directory
uv run --directory /path/to/working/directory --python 3.12 script.py

# Using Python's os.chdir (within script)
python -c "import os; os.chdir('/path/to/dir'); exec(open('script.py').read())"

Temporary PATH Modification

For Single Commands

# Prepend Python to PATH for one command
PATH=~/.pyenv/versions/3.12.4/bin:$PATH python script.py

# UV Python on Linux
PATH=~/.local/share/uv/python/cpython-3.12.6-linux-x86_64-gnu/bin:$PATH python script.py

# With working directory
cd /path/to/dir && PATH=~/.pyenv/versions/3.12.4/bin:$PATH python script.py

Windows:

set PATH=C:\Users\username\AppData\Local\uv\python\cpython-3.12.6-windows-x86_64;%PATH% && python script.py

UV Run Command

Basic Usage

# Run with specific Python version
uv run --python 3.12 script.py

# Run with specific patch version
uv run --python 3.12.6 script.py

# Run with direct path
uv run --python /path/to/python script.py

# Run with working directory
uv run --directory /path/to/dir --python 3.12 script.py

Advanced Patterns

# Run with arguments
uv run --python 3.12 script.py arg1 arg2 --flag

# Run with environment variables
ENV_VAR=value uv run --python 3.12 script.py

# Run module
uv run --python 3.12 -m module_name

# Run with specific requirements
uv run --python 3.12 --with requests --with pandas script.py

Shebang Lines

Direct Path Shebangs

UV Python:

#!/home/user/.local/share/uv/python/cpython-3.12.6-linux-x86_64-gnu/bin/python3
import sys
print(sys.version)

Pyenv Python:

#!/home/user/.pyenv/versions/3.12.4/bin/python3.12
import sys
print(sys.version)

System Python:

#!/usr/bin/python3
import sys
print(sys.version)

env-based Shebangs

#!/usr/bin/env python3
# Uses first python3 found in PATH

#!/usr/bin/env python
# Uses first python found in PATH

Cross-Platform Compatibility

Path Separators

Linux/macOS:

# Use forward slashes
~/.local/share/uv/python/cpython-3.12.6-linux-x86_64-gnu/bin/python3

Windows:

# Use backslashes or forward slashes
%LOCALAPPDATA%\uv\python\cpython-3.12.6-windows-x86_64\python.exe
C:/Users/username/AppData/Local/uv/python/cpython-3.12.6-windows-x86_64/python.exe

Platform Detection

import platform
import sys

# Get platform info
print(platform.system())      # Windows, Linux, Darwin
print(platform.machine())     # x86_64, aarch64, AMD64
print(sys.version_info)       # (3, 12, 6, 'final', 0)

# Construct UV Python path
import os
from pathlib import Path

if platform.system() == "Windows":
    uv_python_dir = Path(os.environ["LOCALAPPDATA"]) / "uv" / "python"
else:
    uv_python_dir = Path.home() / ".local" / "share" / "uv" / "python"

Finding Python Installations

UV Python Discovery

# Find specific version
uv python find 3.12

# Output:
# /home/user/.local/share/uv/python/cpython-3.12.6-linux-x86_64-gnu/bin/python3

# List all installed
uv python list --installed

# Output:
# cpython-3.12.6-linux-x86_64-gnu    /home/user/.local/share/uv/python/...
# cpython-3.11.8-linux-x86_64-gnu    /home/user/.local/share/uv/python/...

Pyenv Python Discovery

# Get global version
pyenv global

# Get path to global Python
pyenv which python

# List all versions
pyenv versions

# Find specific version path
echo ~/.pyenv/versions/$(pyenv global | head -1)/bin/python

System Python Discovery

# Find Python in PATH
which python3       # Linux/macOS
where python        # Windows

# Find all Python installations
whereis python3     # Linux

# Check Python version
python3 --version

Creating Symlinks and Wrappers

Symlinks (Linux/macOS)

# Create symlink to specific UV Python
ln -s ~/.local/share/uv/python/cpython-3.12.6-linux-x86_64-gnu/bin/python3 \
      ~/bin/python3.12

# Create symlink to pyenv Python
ln -s ~/.pyenv/versions/3.12.4/bin/python3.12 \
      ~/bin/python3.12.4

# Add ~/bin to PATH in .bashrc or .zshrc
export PATH="$HOME/bin:$PATH"

Wrapper Scripts

Linux/macOS:

# Create wrapper script
cat > ~/bin/python3.12 << 'EOF'
#!/bin/bash
exec ~/.local/share/uv/python/cpython-3.12.6-linux-x86_64-gnu/bin/python3 "$@"
EOF

chmod +x ~/bin/python3.12

Windows (Batch):

@echo off
C:\Users\username\AppData\Local\uv\python\cpython-3.12.6-windows-x86_64\python.exe %*

Windows (PowerShell):

# Save as python3.12.ps1
& "C:\Users\username\AppData\Local\uv\python\cpython-3.12.6-windows-x86_64\python.exe" @args

PYTHONPATH Configuration

Adding Module Search Paths

# Add directory to Python module search path
export PYTHONPATH=/path/to/modules:$PYTHONPATH

# Windows
set PYTHONPATH=C:\path\to\modules;%PYTHONPATH%

# Use in command
PYTHONPATH=/path/to/modules python script.py

Note: PYTHONPATH adds to module search path but doesn't change working directory.

Best Practices

Version Management

1. Use UV for Python version management - Faster and more reliable than manual downloads 2. Pin versions in projects - Create .python-version file for consistency 3. Use `uv python list --installed` - Track what's installed 4. Clean old versions - Remove unused Python installations periodically

Path Management

1. Use direct paths when needed - More reliable than PATH manipulation 2. Document required Python version - In README.md or requirements 3. Use `uv run --python` - When you need specific version for script 4. Create wrapper scripts - For frequently used specific versions

Cross-Platform

1. Use pathlib - For cross-platform path handling in Python 2. Document platform differences - In configuration or setup guides 3. Test on target platforms - Don't assume path compatibility 4. Use environment variables - For platform-specific paths

Troubleshooting

Python Version Not Found

Symptoms:

• "Python 3.x not found"
• Version mismatch errors

Solutions:

# List installed versions
uv python list --installed

# Install missing version
uv python install 3.12

# Verify installation
uv python find 3.12

# Check PATH
echo $PATH | grep python

Version Conflict

Symptoms:

• Wrong Python version executing
• Unexpected module not found errors

Solutions:

# Pin version for project
uv python pin 3.12

# Use explicit version in command
uv run --python 3.12 script.py

# Check which Python is being used
which python
python --version

# Use full path to avoid ambiguity
~/.local/share/uv/python/cpython-3.12.6-linux-x86_64-gnu/bin/python3 script.py

PATH Issues

Symptoms:

• Commands not found
• Wrong version executing

Solutions:

# Check current PATH
echo $PATH

# Add UV Python to PATH (temporary)
export PATH="$HOME/.local/share/uv/python/cpython-3.12.6-linux-x86_64-gnu/bin:$PATH"

# Add to shell profile permanently (.bashrc, .zshrc)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Permission Errors

Symptoms:

• Cannot write to Python directory
• Installation fails

Solutions:

# Check Python installation directory permissions
ls -la ~/.local/share/uv/python/

# Fix permissions
chmod -R u+w ~/.local/share/uv/python/

# Use custom install directory
export UV_PYTHON_INSTALL_DIR=$HOME/python-versions
uv python install 3.12

Recommended Approaches

For Different Use Cases

One-off commands:

# Use uv run
uv run --python 3.12 script.py

Scripts with shebangs:

#!/usr/bin/env python3
# Or use direct path for specific version

Applications needing specific version:

# Use direct path in configuration
python_path = "/home/user/.local/share/uv/python/cpython-3.12.6-linux-x86_64-gnu/bin/python3"

Working with specific directories:

# Use uv run with --directory
uv run --directory /path/to/project --python 3.12 script.py

Comprehensive Python management:

# Use UV for installation and management
uv python install 3.12
uv python pin 3.12
uv run python script.py

Summary

UV provides comprehensive Python version management:

• Automatic installation of Python versions
• Version pinning with .python-version files
• Direct path access for shell-independent execution
• Cross-platform compatibility with consistent interfaces
• Fast performance compared to manual downloads
• Integration with existing Python tools (pyenv, system Python)

Use uv python install for version management and uv run --python for version-specific script execution.