Migrate from pyenv to mise: Complete Guide for Python 3.12 to 3.13 Upgrades

If you’re currently using pyenv for Python version management, mise offers a modern alternative worth considering. Written in Rust, mise provides faster shim activation, support for multiple languages, built-in tasks, and automatic per-project environments. In this guide, we’ll walk through uninstalling pyenv, installing mise, migrating your configurations, and upgrading from Python 3.12 to 3.13 together.

Why Consider Migrating from pyenv to mise?\n\nYou’ll often need different Python versions across projects. While system package managers provide one version tied to your OS, tools like pyenv let you install multiple Pythons locally and switch per project using .python-version files and shims—lightweight executables that redirect to the right version.\n\nPyenv serves Python workflows effectively but remains Python-only, with shim activation adding overhead and no native support for other languages or task execution.\n\nMise extends this model. It evolved from asdf—a shell-based multi-runtime manager—with Rust ports like rtx leading to mise’s focus on speed and added features like task running (mise run) and automatic env vars.\n\nOf course, you have options: stick with pyenv for Python purity, use asdf for shell-based multi-lang, or rtx for another Rust alternative. Mise offers performance gains but is newer than pyenv; weigh your multi-tool needs against maturity.\n\nHere’s how mise improves on pyenv:\n- Performance: Rust implementation resolves shims faster than pyenv’s shell scripts.\n- Multi-language support: Manages Python with Node.js, Ruby, Go, Rust, and others.\n- Project environments: Automatically applies env vars by directory, akin to direnv.\n- Task running: Built-in runner like Make or Just.\n- Python support: Tracks releases closely, including 3.13.\n\nThis setup suits upgrading from Python 3.12 to 3.13, where you’ll encounter features like better error messages—though check for breaking changes.

Prerequisites\n\n- macOS/Linux (Windows via WSL).\n- Homebrew (optional).\n- Back up your .python-version files from projects.\n\n## Mise Fundamentals\n\nBefore the steps, let’s clarify mise’s core concepts—they parallel pyenv but extend further.\n\nShims: Like pyenv, mise places shims in your PATH. These detect the project via .tool-versions and exec the correct tool version. Rust makes resolution faster.\n\n**.tool-versions**: Successor to .python-version. Format: python 3.13.0 or multi-line python 3.13.0\nnodejs 20. Supports global/project settings.\n\nmise use/install: mise use python@3.13 installs if needed, sets local/global. mise install only installs without setting.\n\nWith that context, let’s uninstall pyenv.\n\n## Step 1: Uninstall pyenv

Remove pyenv completely:

bash\n# If installed via Homebrew:\n$ brew uninstall pyenv pyenv-virtualenv\n\n# Output similar to:\n# ==> Uninstalling Cask pyenv\n# ==> Purging files for pyenv...\n\n$ rm -rf ~/.pyenv\n\n# Removes pyenv and cached Pythons.\n\n# Edit ~/.zshrc or ~/.bashrc, remove pyenv init lines like:\n# export PYENV_ROOT=\"$HOME/.pyenv\"\n# export PATH=\"$PYENV_ROOT/bin:$PATH\"\n# eval \"$(pyenv init -)\"\n\n$ exec $SHELL\n\n# Verify uninstall:\n$ pyenv --version\n# zsh: command not found: pyenv\ngood.\n\n\nThis ensures no remnants interfere with mise.

Step 2: Install mise

bash\n$ curl https://mise.run | sh\n\n# Downloads and installs mise to ~/.local/share/mise.\n# Output ends with: mise 2024.7.2\n# Add to PATH or activate (next step).\n

Add to shell (e.g., ~/.zshrc):

bash\necho 'eval \"$(mise activate zsh)\"' >> ~/.zshrc\n\n# Activates shims/envs in new shells.\n\n$ exec $SHELL\n\n$ mise --version\n# mise 2024.7.2\n\n\nNow mise is active; shims in PATH.

Step 3: Migrate Python Versions from pyenv

List pyenv versions (if remnants):

bash\n# Recall or list backed-up versions, e.g., 3.12.5\n\n\nInstall/set versions:\n\nbash\n$ mise use --global python@3.12\n\n# Installs if missing, sets global in ~/.config/mise/config.toml\n# Long output: resolved python@3.12.7, downloading..., installed.\n\n$ mise use python@3.13.0\n\n# Sets local .tool-versions: python 3.13.0\n# Installs 3.13.0 if needed.\n

Step 4: Update Config Files

In your project directory:\n\nbash\n$ mv .python-version .tool-versions\n\n\nMise now uses .tool-versions—compatible with asdf. List contents if multi-tool:\n\npython 3.13.0\nnodejs 20\n\nActivate shell or new terminal to pick it up.

Step 5: Verify Migration

bash\n$ python --version\nPython 3.13.0\n\n$ pip --version\npip 24.2 from /home/user/.local/share/mise/installs/python/3.13.0/lib/python3.13/site-packages/pip (python 3.13)\n\n$ which python\n/home/user/.local/share/mise/installs/python/3.13.0/bin/python\n\n\nIf you have a mise.toml with [tasks.test=“pytest”], run:\n\n$ mise run test

Upgrading Projects to Python 3.13

Follow these steps for a project:\n\n1. cd your-project\n2. Update .tool-versions (or create): echo \"python 3.13.0\" > .tool-versions\n3. $ mise install — installs Python 3.13.0 if missing.\n4. $ python -m pip install --upgrade pip\n5. Update dependencies: $ pip install -r requirements.txt\n6. Run tests: $ pytest (or your test command).

Handle breaking changes: Check Python 3.13 What’s New.

Troubleshooting

• Shims or PATH issues: $ mise doctor — checks activation, shims, configs. Example output flags missing eval in .zshrc.\n- Downloads fail (403/429): Export $ export MISE_GITHUB_TOKEN=ghp_... (GitHub PAT, no scopes needed).\n- Wrong version active: $ mise deactivate; mise activate zsh or check .tool-versions hierarchy (local > global).\n- Legacy pyenv interference: Ensure PATH clean, grep -r pyenv ~/.config/.\n- Virtualenvs: Recreate with mise exec -- python -m venv .venv.

Conclusion

You’ve now migrated from pyenv to mise with Python 3.13 ready. Dive into mise tasks or multi-language setups via the docs. Share your experience below or run mise doctor for checks.