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.

OMG maintainers · Updated · Source-reviewed guide

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

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

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

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

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

omg which python
which -a python3
python3 --version

Sources and verification

Commands and behavior are based on the references below. Source review is not a claim that every workflow has been executed on every supported platform.

Read as Markdown