What Python Implementations and Variants Does uv-python Support? A Complete Guide

uv-python supports four distinct Python implementations: CPython (cpython/cp), PyPy (pypy/pp), GraalPy (graalpy/gp), and Pyodide (pyodide).

The uv toolchain from astral-sh/uv uses the uv-python crate to handle Python discovery, downloading, and version management across these implementations. Understanding which Python variants are supported—and how to reference them—ensures you can install and manage the exact interpreter your project requires.

The Four Supported Python Implementations in uv-python

The uv-python library recognizes implementations through the ImplementationName enum defined in crates/uv-python/src/implementation.rs. This enum maps user-facing strings to internal variants, supporting both long-form names and short aliases for CLI convenience.

CPython

CPython is the reference implementation of Python, distributed primarily through the python-build-standalone project. In uv, you can request CPython using either cpython or the short alias cp.

The implementation is identified internally as ImplementationName::CPython. When you run uv python install without specifying an implementation, uv defaults to CPython.

PyPy

PyPy is a JIT-enabled alternative implementation offering significant performance improvements for certain workloads. uv-python supports PyPy versions up to Python 3.11.

You can specify PyPy using pypy or the short alias pp. The internal enum variant is ImplementationName::PyPy. PyPy distributions are handled separately from CPython in the download logic located in crates/uv-python/src/downloads.rs.

GraalPy

GraalPy is a high-performance implementation built on the GraalVM polyglot runtime. It allows Python code to interoperate with other JVM languages and leverages GraalVM's optimizing compiler.

In uv commands, use graalpy or the short alias gp. Internally, this maps to ImplementationName::GraalPy. The implementation detection logic treats GraalPy as a distinct variant from CPython when resolving interpreter paths.

Pyodide

Pyodide is a WebAssembly-based port of CPython designed for browser execution and WebAssembly runtimes. Unlike the other implementations, Pyodide does not have a short alias—you must specify it as pyodide exactly.

The internal representation is ImplementationName::Pyodide. This variant is particularly relevant for projects targeting WebAssembly environments or requiring Python execution in sandboxed browser contexts.

How uv-python Identifies Implementations in Source Code

The core logic for implementation detection resides in crates/uv-python/src/implementation.rs. Here, the ImplementationName enum defines the four supported variants:

// Simplified representation of the enum structure
pub enum ImplementationName {
    CPython,
    PyPy,
    GraalPy,
    Pyodide,
}

The crate implements FromStr for ImplementationName, enabling case-insensitive parsing of both long and short names. For example, the string "cp" parses to ImplementationName::CPython, while "graalpy" maps to ImplementationName::GraalPy. If an unknown implementation string is provided, the parser returns Error::UnknownImplementation.

The pretty() method on the enum returns human-readable display names, while executable_name() provides the appropriate binary name for each implementation (e.g., "python" for CPython, "pypy" for PyPy).

Installing Specific Python Implementations with uv

You can specify which Python implementation to install or use via the --implementation flag (or -i shorthand) in uv python install commands. The parser accepts any of the long or short aliases defined in the ImplementationName enum.

Install CPython using the long form:

uv python install 3.12.1 --implementation cpython

Install PyPy using the short alias:

uv python install 3.10 --implementation pp

Install GraalPy:

uv python install 24.2.2 --implementation gp

Install Pyodide (note that only the long name is accepted):

uv python install 0.27.0 --implementation pyodide

When listing installed interpreters, uv python list displays the implementation prefix for non-CPython variants:

$ uv python list
cpython3.12.0    (managed)
pypy3.10.0       (managed)
graalpy3.10.0    (managed)
pyodide3.12.0    (managed)

Programmatic Usage in Rust

When using uv-python as a library in Rust projects, you can parse implementation strings directly using the ImplementationName type:

use uv_python::ImplementationName;

fn main() -> Result<(), uv_python::Error> {
    // Parse short alias "gp" into GraalPy
    let impl_name: ImplementationName = "gp".parse()?;
    
    // Get the executable name for the implementation
    let exe = impl_name.executable_name(); // returns "graalpy"
    
    // Get pretty display name
    println!("Selected: {}", impl_name.pretty()); // prints "GraalPy"
    
    Ok(())
}

The LenientImplementationName variant is also available for parsing user input with more flexible matching rules, though ImplementationName is the strict enum used internally for validation.

Summary

• uv-python supports four implementations: CPython (cp/cpython), PyPy (pp/pypy), GraalPy (gp/graalpy), and Pyodide (pyodide only).
• Implementation detection is handled by the ImplementationName enum in crates/uv-python/src/implementation.rs, which provides case-insensitive parsing of long and short names.
• CLI usage requires the --implementation flag with uv python install, accepting any valid alias for the target interpreter.
• Pyodide lacks a short alias, requiring the full pyodide string, while other implementations offer convenient two-letter shortcuts.

Frequently Asked Questions

Does uv-python support IronPython or Jython?

No, uv-python currently only supports CPython, PyPy, GraalPy, and Pyodide. IronPython and Jython are not defined in the ImplementationName enum and will trigger an Error::UnknownImplementation if specified. The maintainers have focused on implementations with standalone distribution channels compatible with uv's installation model.

Can I use short aliases like 'cp' or 'pp' in uv commands?

Yes, uv accepts both long names and short aliases for implementations. You can use cp for CPython, pp for PyPy, and gp for GraalPy. These aliases are case-insensitive, so CP, Cp, and cp are all valid. The parser normalizes these to the internal ImplementationName enum variants before processing.

How does uv handle Pyodide since it lacks a short alias?

Pyodide must be specified using the full name pyodide in all uv commands. The ImplementationName enum does not define a short alias for Pyodide (unlike the two-letter codes for other implementations). When parsing implementation strings, uv matches pyodide exactly to ImplementationName::Pyodide, rejecting abbreviated forms like pd or py.

Where is the implementation detection logic defined in the uv source code?

The core logic resides in crates/uv-python/src/implementation.rs, which defines the ImplementationName enum and its FromStr implementation. This file handles the mapping between user-provided strings (like "gp" or "pypy") and internal enum variants. The download logic in crates/uv-python/src/downloads.rs then uses these variants to fetch the correct distribution binaries for each implementation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}