pyenv-native

Native Rust Python version manager inspired by pyenv. Ships pyenv (CLI), pyenv-mcp (agents), and pyenv gui.

Windows, Linux, and macOS are supported. Android/Termux is experimental (source builds).

---

Install

Pick the block for the machine you are on. Coding agents: run that block, then pyenv doctor. Do not guess a classic bash-pyenv install.

Windows (PowerShell 7+)

irm https://github.com/imyourboyroy/pyenv-native/releases/latest/download/install.ps1 | iex
pyenv doctor

Linux / macOS / Termux

curl -fsSL https://github.com/imyourboyroy/pyenv-native/releases/latest/download/install.sh | sh
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$("$HOME/.pyenv/bin/pyenv" init - bash)"   # use zsh or fish if that is your shell
pyenv doctor

Open a new terminal after install so shims are on PATH. On Termux, install compilers first: pkg install clang make pkg-config libffi openssl readline ncurses.

pipx (any OS with Python)

pipx install pyenv-native
pyenv-native install --install-root "$HOME/.pyenv"

Winget and Homebrew manifests are generated on each release (dist/winget/, dist/homebrew/) but are not published yet. Do not run winget install or brew install for pyenv-native.

Full handbook (shells, tags, custom roots): docs/INSTRUCTIONS.md

---

After install

pyenv install 3.14          # latest matching 3.14.x
pyenv global 3.14
pyenv venv create 3.14 app
pyenv local 3.14/envs/app
pyenv which python
pyenv gui                   # optional desktop UI

Managed venvs live under PYENV_ROOT/venvs/<runtime>/<name>. Version selection is shell → local .python-version → parents → global → system.

---

Upgrade / uninstall

	Windows	Linux / macOS
Upgrade	Re-run install.ps1, or pyenv self-update --yes	Re-run install.sh, or pyenv self-update --yes
Uninstall	pyenv self-uninstall, or irm …/uninstall.ps1 | iex	pyenv self-uninstall, or curl …/uninstall.sh | sh -s -- --remove-root

pipx: pipx upgrade pyenv-native then pyenv-native install --install-root "$HOME/.pyenv".

---

For coding agents

1. If pyenv-mcp is connected: get_toolkit_guide → resolve_project_environment → ensure_runtime → ensure_project_venv. Details: docs/MCP.md.
2. If MCP is missing: install with the OS command above, then CLI (pyenv local, pyenv install, pyenv venv create, pyenv which python).
3. Never pip install into an unknown global Python. Resolve the interpreter first.

Register MCP: pyenv-mcp print-config (paste into Cursor MCP settings). Quick JSON: pyenv-mcp guide.

Install agent skills (Cursor, Claude Code, Gemini CLI, Copilot, and more):

Install the agent skills from https://github.com/imyourboyroy/pyenv-native

# Windows (PowerShell 7+)
git clone --depth 1 https://github.com/imyourboyroy/pyenv-native.git
cd pyenv-native
./scripts/install-agent-skills.ps1 -Agent all

# macOS / Linux
git clone --depth 1 https://github.com/imyourboyroy/pyenv-native.git
cd pyenv-native
chmod +x ./scripts/install-agent-skills.sh
./scripts/install-agent-skills.sh --agent all

Guides: docs/agent-skills/README.md · getting-started.md

---

GUI

Launch with pyenv gui after a native install. Native bundles for Windows, Linux, and macOS ship pyenv-gui next to pyenv. Standalone binaries and .sha256 files are on GitHub Releases.

Dashboard	Install Runtimes	Installed	Venvs

More views and feature notes: docs/GUI.md

---

Languages

The GUI, CLI, doctor, and installer follow the OS language, or a choice in Settings / the sidebar switcher (ui.language, or PYENV_LANG).

English · 简体中文 · Español · 日本語 · 한국어 · Português (Brasil) · Français · Deutsch · Русский · فارسی · العربية · हिन्दी · Italiano · Türkçe

zh and zh-TW use Simplified Chinese (no Traditional catalog). Command names, paths, and versions stay English. Product docs (README.md, docs/*.md) stay English. I18N

---

Docs

INSTRUCTIONS	Install, shell init, workflows, troubleshooting
CLI	Command reference
MCP	Agent tools and recommended order
GUI	Desktop companion
I18N	GUI/CLI/doctor languages, locale tags, fonts

---

Issues

Open an issue with OS, architecture, shell, pyenv doctor output, and logs from .pyenv/logs/. Run pyenv preflight before source installs on macOS, Linux, or Android.

pyenv-native is an independent reimplementation inspired by pyenv. It is not affiliated with or endorsed by the official pyenv project.

Created by: Roy Dawson IV | GitHub | PyPI | License: MIT

Simplified Chinese localization by KiniMail inspired first-class in-app language support. That work is credited as motivation; this tree does not use KiniMail dictionaries or tagging.