# Manage Python versions and virtual environments

Download precompiled standalone CPython with SHA-256 validation, detect pyproject.toml and .python-version pins, and isolate dependencies in virtual environments.

Canonical: https://getomg.xyz/runtimes/python/
Updated: 2026-09-22
Author: OMG maintainers

## Precompiled CPython from standalone builds

Compiling Python from source on every new machine requires C build toolchains, header files, and system development packages (like zlib, openssl, and libffi). OMG avoids this overhead by downloading validated, precompiled CPython distributions from the `python-build-standalone` project (`src/runtimes/python.rs` and `src/runtimes/python/catalog.rs`).

The published OMG release queries python-build-standalone releases on GitHub to select a binary matching the host platform target. It downloads the archive, validates its SHA-256 digest, and performs a pure-Rust `.tar.gz` extraction into a staged directory. Once extracted, the interpreter is published atomically to `~/.local/share/omg/versions/python/<version>`.

### Install and switch Python versions

```sh
omg use python 3.12
omg use python 3.11
omg list python
omg which python
```

Published OMG releases target Linux x86_64 and Apple Silicon macOS. On Windows, run OMG inside WSL; Intel macOS and Linux ARM64 are not published release targets.

## Project version detection and pyproject.toml support

OMG’s shell hook (`src/hooks/mod.rs`) searches the current directory and then its ancestors. The nearest directory with a Python requirement wins. Within one directory, the sources are checked in this order:

1. Project `.python-version` file: first priority within the same directory.

2. `pyproject.toml`: OMG reads the `[project] requires-python` specification if no `.python-version` is present.

3. `.tool-versions`: multi-runtime configuration file for asdf and mise compatibility.

### Verify Python version selection

```sh
python3 --version
omg which python
which -a python3
```

## Virtual environments and dependency boundaries

OMG provides the selected Python interpreter. Project libraries should be isolated in a standard virtual environment created by that interpreter. This maintains a clean boundary between runtime management and package dependencies.

### Create and use an isolated virtual environment

```sh
python3 -m venv .venv
.venv/bin/python --version
.venv/bin/pip install -r requirements.txt
```

> OMG’s task runner discovers [tool.poetry.scripts] entries in pyproject.toml and [scripts] entries in Pipfile, with Python task priority 80. It does not currently discover PDM, Rye, or [project.scripts] entries.

## Diagnosing system Python conflicts

Most Linux distributions and macOS ship a system-managed Python for operating-system utilities. OMG does not overwrite or mutate system Python packages in `/usr/bin/python3`. Instead, OMG manages user-space versions under `~/.local/share/omg/versions/python` and prepends the active symlink to your PATH.

### Check interpreter locations across your PATH

```sh
omg which python
which -a python3
python3 --version
```

## Sources and verification

Source-reviewed guidance; not a claim of execution on every supported platform.

- [OMG Python manager implementation (src/runtimes/python.rs)](https://getomg.xyz/docs/runtimes/)

- [python-build-standalone GitHub releases](https://github.com/indygreg/python-build-standalone/releases)

- [Python venv documentation](https://docs.python.org/3/library/venv.html)

## Related pages

- https://getomg.xyz/compare/omg-vs-pyenv/

- https://getomg.xyz/guides/reproducible-dev-environments/

- https://getomg.xyz/docs/troubleshooting/