# pyenv — Simple Python Version Management

> Install and switch between multiple Python versions per-project with a single CLI tool that stays out of your way.

## Install

Save as a script file and run:

# pyenv — Simple Python Version Management

## Quick Use
```bash
curl https://pyenv.run | bash
# add to shell profile:
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
# install and activate a version:
pyenv install 3.12.4
pyenv global 3.12.4
```

## Introduction
pyenv lets you install and switch between multiple Python versions without touching the system Python. It uses shims and per-directory `.python-version` files so every project can pin exactly the interpreter it needs.

## What pyenv Does
- Installs any CPython, PyPy, Anaconda, or Stackless version from source
- Switches the active Python globally, per-directory, or per-shell session
- Supports `.python-version` files for automatic per-project switching
- Manages shims in `~/.pyenv/shims` so the right binary is always on PATH
- Works alongside virtualenvs via the pyenv-virtualenv plugin

## Architecture Overview
pyenv inserts a directory of lightweight shim scripts at the front of your PATH. When you run `python`, the shim inspects `PYENV_VERSION`, the local `.python-version` file, or the global setting to resolve the correct interpreter binary under `~/.pyenv/versions/`. Versions are compiled from source using python-build, which ships as a built-in plugin.

## Self-Hosting & Configuration
- Install via `pyenv-installer` one-liner or clone the repo to `~/.pyenv`
- Requires common build dependencies (gcc, make, libssl-dev, zlib, etc.)
- Set `PYENV_ROOT` to relocate the installation directory
- Use `pyenv local 3.x.y` in a project to create a `.python-version` file
- Add `pyenv-virtualenv` plugin for integrated virtualenv management

## Key Features
- Zero dependency on system Python — fully self-contained
- Per-directory version switching with automatic detection
- Builds Python from source so any version is available
- Plugin system for virtualenv, pip-rehash, and more
- Shell completion for bash, zsh, and fish

## Comparison with Similar Tools
- **asdf** — universal version manager for many languages but heavier setup for Python-specific needs
- **mise** — Rust-based polyglot tool manager with TOML config; newer ecosystem
- **conda** — full environment and package manager oriented toward data science, not just version switching
- **uv** — ultra-fast package installer that can manage Python versions but focuses on dependency resolution
- **deadsnakes PPA** — Ubuntu-only; limited to versions the PPA maintainers choose to publish

## FAQ
**Q: Does pyenv work on macOS and Linux?**
A: Yes. macOS and most Linux distributions are fully supported. Windows users should use pyenv-win, a separate port.

**Q: Can I use pyenv with virtualenvs?**
A: Yes. The pyenv-virtualenv plugin lets you create, list, and auto-activate virtualenvs tied to specific Python versions.

**Q: Does pyenv interfere with system Python?**
A: No. It only prepends shims to your PATH; the system Python remains untouched.

**Q: How do I uninstall a Python version?**
A: Run `pyenv uninstall 3.x.y`. The compiled files are removed from `~/.pyenv/versions/`.

## Sources
- https://github.com/pyenv/pyenv
- https://github.com/pyenv/pyenv/wiki

---
Source: https://tokrepo.com/en/workflows/2f01ea4b-4211-11f1-9bc6-00163e2b0d79
Author: Script Depot