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:

```bash
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:

```bash
# 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](references/recent-changes.md) 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:

| Command | Purpose | Example |
|---------|---------|---------|
| `uv pip install` | Install packages in current environment | `uv pip install requests` |
| `uv tool install` | Install CLI tools globally with isolation | `uv tool install black` |
| `uvx` | Execute packages in temporary environments | `uvx mcp-server-sqlite` |
| `uv venv` | Create virtual environments | `uv venv .venv` |
| `uv python install` | Install Python versions | `uv python install 3.12` |

### 2. Tool vs UVX Decision Tree

```text
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):**

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

**Local Development (Use --from flag):**

```json
{
  "servers": {
    "my-server": {
      "command": "uvx",
      "args": [