Skip to main content
skill CX Codex

uv-python-versions — Claude Code skill for Python versions

uv-python-versions is a Claude Code skill for managing CPython and PyPy with uv. Install interpreters, pin a project version, or switch versions for testing.

MIT 332 installs ★ 60 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add laurigates/claude-plugins --skill uv-python-versions -a claude-code
Open on GitHub

What uv-python-versions does

This skill guides uv commands for installing Python versions, checking which interpreters are available, and locating a particular one. It also covers pinning a project version with .python-version and working with the requires-python constraint in pyproject.toml.

For multi-version tests, run commands with uv run --python or create separate environments using uv venv --python. The guidance covers both CPython and PyPy. Project libraries and global CLI tools are separate tasks, not part of this skill.

What it helps with

  • install a specific CPython or PyPy version
  • pin a Python version in .python-version
  • locate an installed interpreter
  • run tests across Python versions
  • create a virtual environment with a chosen interpreter

Example prompts for the agent

  • Install Python 3.12 and pin it for this project.
  • List installed Python versions and find interpreter 3.11.
  • Show me how to run pytest with Python 3.10 and 3.12 using uv.

How to install uv-python-versions

1Skills CLI (Vercel)

npx skills add laurigates/claude-plugins --skill uv-python-versions -a claude-code

2Manually: put the files in place

~/.claude/skills/uv-python-versions/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/uv-python-versions/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about uv-python-versions

How do I install uv-python-versions in Claude Code?

Run npx skills add laurigates/claude-plugins --skill uv-python-versions -a claude-code. The skill file is placed at ~/.claude/skills/uv-python-versions/SKILL.md.

What does uv-python-versions do?

It provides guidance for installing and locating CPython and PyPy with uv, and for selecting a Python version for a project.

Can uv-python-versions help test across Python versions?

Yes. It covers running commands with uv run --python and creating separate environments with uv venv --python.

Source text

SKILL.md · MIT
---
created: 2025-12-16
modified: 2026-11-14
reviewed: 2026-04-25
name: uv-python-versions
description: Install and manage Python interpreter versions with uv. Use when the user mentions installing Python versions, .python-version, uv python, or managing CPython/PyPy.
user-invocable: false
allowed-tools: Bash(uv python install), Bash(uv python list), Bash(uv python list --only-installed), Bash(uv python list --verbose), Bash(uv python find), Bash(uv venv *), Bash(uv init *), Read, Grep, Glob
---

# UV Python Version Management

Quick reference for installing and managing Python interpreter versions with UV.

## When to Use This Skill

| Use this skill when... | Use a focused sibling instead when... |
|---|---|
| Installing a specific CPython or PyPy interpreter with `uv python install` | Adding a Python library to a project — use uv-project-management |
| Pinning a project to a Python version via `.python-version` or `requires-python` | Installing a global Python CLI tool — use uv-tool-management |
| Switching between multiple installed interpreters for testing | Running a script with auto-managed Python — use uv-run |

## When This Skill Applies

- Installing specific Python versions
- Switching between multiple Python versions
- Pinning Python versions for projects
- Managing CPython and PyPy interpreters
- Finding and listing installed Python versions

## Quick Reference

### Installing Python Versions

```bash
# Install latest Python
uv python install

# Install specific version
uv python install 3.11
uv python install 3.12
uv python install 3.10 3.11 3.12

# Install exact version
uv python install 3.11.5
uv python install [email protected]

# Install PyPy
uv python install [email protected]
uv python install [email protected]
```

### Listing Python Versions

```bash
# List all available versions
uv python list

# List only installed versions
uv python list --only-installed

# List with verbose details
uv python list --verbose
```

### Pinning Python Versions

```bash
# Pin version for current project
uv python pin 3.11
uv python pin 3.12.1

# Pin PyPy
uv python pin [email protected]

# Pin with version file
# Creates/updates .python-version
```

### Finding Python Interpreters

```bash
# Find any Python installation
uv python find

# Find specific version
uv python find 3.11
uv python find 3.12

# Find PyPy
uv python find pypy
uv python find [email protected]
```

### Using Specific Python Versions

```bash
# In project commands
uv run --python 3.11 script.py
uv run --python 3.12 pytest

# Creating virtual environments
uv venv --python 3.11
uv venv --python 3.10 .venv-py310

# Initializing projects
uv init --python 3.12 my-project
```

## Python Version Sources

UV searches for Python in this order:
1. **UV-managed** - Installed via `uv python install`
2. **.python-version** - Pin file in project directory
3. **pyproject.toml** - `requires-python` field
4. **System Python** - Existing system installations
5. **Environment** - `$PATH` and standard locations

## Version Pinning

### .python-version File

```bash
# Pin creates this file
uv python pin 3.11

# File contents
3.11

# Exact version
uv python pin 3.11.5
```

### pyproject.toml

```toml
[project]
requires-python = ">=3.11"

# UV respects this constraint
```

## Supported Python Implementations

### CPython

```bash
# Default implementation
uv python install 3.11
uv python install [email protected]
uv python install [email protected]
```

### PyPy

```bash
# Alternative Python implementation
uv python install [email protected]
uv python install [email protected]
```

## Common Commands

```bash
# Install and pin latest Python 3.12
uv python install 3.12 && uv python pin 3.12

# Install multiple versions for testing
uv python install 3.10 3.11 3.12

# Check which Python is active
uv python find
uv run python --version

# Uninstall version (manual)
rm -rf ~/.local/share/uv/python/cpython-3.11.5-*
```

## Integration with Projects

### Project Initialization

```bash
# Initialize with specific Python
uv init --python 3.11 my-project

# Generates .python-version
cat .python-version
# 3.11
```

### Running Commands

```bash
# Use project's pinned Python
uv run python script.py

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

# Use system Python
uv run --python python3 script.py
```

## Multi-Version Testing

```bash
# Test across Python versions
uv run --python 3.10 pytest
uv run --python 3.11 pytest
uv run --python 3.12 pytest

# Create version-specific venvs
uv venv --python 3.10 .venv-py310
uv venv --python 3.11 .venv-py311
uv venv --python 3.12 .venv-py312
```

## Key Features

- **Fast downloads**: Parallel downloads with caching
- **Automatic**: Downloads versions on-demand
- **Isolated**: UV-managed versions don't conflict with system Python
- **Portable**: Uses standalone Python distributions
- **Cross-platform**: Works on Linux, macOS, and Windows

## See Also

- `uv-project-management` - Using pinned Python versions in projects
- `uv-workspaces` - Python versions in monorepos
- `python-testing` - Testing across multiple Python versions

## References

- Official docs: https://docs.astral.sh/uv/guides/install-python/
- Python standalone builds: https://github.com/indygreg/python-build-standalone
- Detailed guide: See REFERENCE.md in this skill directory

© laurigates · MIT · laurigates/claude-plugins

Similar skills

All skills for Programming languages →

From the same set27

The whole set →
basedpyright-type-checking basedpyright-type-checking sets up strict Python type checking using basedpyright, compares it against mypy, and guides configuration in pyproject.toml. CX Codex +1 357installs uv-workspaces A skill for multi-package Python projects on uv: workspace setup, a shared lockfile, and dependencies between members. CX Codex +1 356installs uv-run uv-run teaches your AI assistant to execute Python scripts via uv and embed dependencies with PEP 723 without manual virtual environment activation. CX Codex +1 342installs python-packaging python-packaging guides the agent through building wheels and sdists with uv, configuring pyproject.toml, and uploading packages to PyPI or Test PyPI. CX Codex +1 336installs uv-advanced-dependencies uv-advanced-dependencies is a skill for managing non-standard dependency sources in uv, including GitHub repositories, editable local packages, and private indexes. It covers projects that need Git, local path, or custom index dependencies. CX Codex +1 332installs uv-tool-management uv-tool-management is a Claude Code skill for managing global Python CLI tools with uv and running them temporarily with uvx, including as an alternative to pipx. CX Codex +1 328installs imagemagick-conversion imagemagick-conversion — a skill for converting, resizing and optimizing images via ImageMagick command-line. Useful for bulk format conversion, thumbnail generation, and large-scale image processing workflows. CX Codex +1 260installs jq-json-processing jq-json-processing — a skill for parsing, filtering and transforming JSON with jq. Extracts fields, filters arrays, reshapes objects and validates syntax. CX Codex +1 245installs

Project sponsors

Companies that keep this analytics open