Mise Migrate From Pyenv

1. Inventory pyenv state.
2. Create mise.toml per project (or enable idiomatic reader).
3. Swap shell rc.
4. Verify.
5. Uninstall pyenv (and pyenv-virtualenv if present).

Step 1 — inventory

pyenv versions                  # installed Python versions
pyenv version                   # current version
pyenv global                    # global default
pyenv local                     # in-project local pin (reads .python-version)
grep -r pyenv ~/.zshrc ~/.bashrc ~/.bash_profile 2>/dev/null
ls .python-version 2>/dev/null  # per-project version file

Also check for pyenv-virtualenv:

pyenv virtualenvs
cat .python-version   # may contain a virtualenv name like "myproject-3.12.7"

pyenv-virtualenv is a plugin that lets .python-version contain a virtualenv name instead of a bare version. If your .python-version has something like myproject-3.12.7, you'll need to handle that separately (see "pyenv-virtualenv migration" below).

Step 2 — mise.toml per project

For a plain .python-version containing 3.12.7:

# mise.toml
[tools]
python = "3.12.7"

Or enable the idiomatic reader and let mise read .python-version directly:

# mise.toml or ~/.config/mise/config.toml
[settings]
idiomatic_version_file_enable_tools = ["python"]

For pre-built binaries (strongly recommended — much faster):

[env]
MISE_PYTHON_COMPILE = "0"

Or set it globally in your shell rc.

Global default

# ~/.config/mise/config.toml
[tools]
python = "3.12"

[env]
MISE_PYTHON_COMPILE = "0"

Step 3 — swap shell rc

Remove pyenv's init:

# ~/.zshrc — DELETE
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - zsh)"
eval "$(pyenv virtualenv-init -)"   # if you had pyenv-virtualenv

Add mise:

eval "$(mise activate zsh)"

Restart shell.

Step 4 — verify

which python            # should be under ~/.local/share/mise/
python --version        # matches mise.toml
cd <project>
python --version        # matches the project's pin

If which python shows a pyenv path, the old PATH is sticky. Check for leftover pyenv lines, then open a fresh terminal.

pyenv-virtualenv migration

pyenv-virtualenv stores .python-version with a venv name (e.g. myproject-3.12.7) and creates a venv under ~/.pyenv/versions/myproject-3.12.7/. mise doesn't have a direct equivalent, but _.python.venv is the idiomatic replacement:

Before (pyenv-virtualenv)

.python-version contains: myproject-3.12.7
Venv lives in:            ~/.pyenv/versions/myproject-3.12.7/

After (mise)

# mise.toml
[tools]
python = "3.12.7"

[env]
_.python.venv = { path = ".venv", create = true }

Venv lives in: .venv/ (in the project dir, gitignored)

.venv/ is in-project instead of centrally located. Pro: easier to blow away and recreate, no centralized cache to prune. Con: every project has its own full venv (but the Python interpreter itself is shared via mise's install dir, so this is less disk-heavy than it sounds).

If you want to keep a pyenv-virtualenv-style centralized layout:

[env]
_.python.venv = { path = "~/.cache/venvs/{{config_root | basename}}", create = true }

Not the idiomatic pattern, but possible.

Step 5 — uninstall pyenv

rm -rf ~/.pyenv
# If installed via Homebrew:
brew uninstall pyenv pyenv-virtualenv

Restart the shell. Verify which pyenv reports not found.

Common issues

"SSL module not available" after migrating

You migrated to mise's compiled Python and the host is missing libssl-dev (or the equivalent). See mise-lang-python-overview → "Build dependencies". Or switch to pre-built: MISE_PYTHON_COMPILE=0 mise install python@<version>.

pip install fails with "externally-managed-environment"

You're pip install-ing into the mise-installed Python's system site (PEP 668 error). Always use a venv:

python -m venv .venv
source .venv/bin/activate
pip install <pkg>

Or, better, use uv or poetry + _.python.venv to manage this for you. See mise-lang-python-packages.

python --version shows a different version than mise current python

Shim cache staleness. Run mise reshim and reopen the shell.

IDE still finds the pyenv Python

Point the IDE at the mise-installed interpreter explicitly:

~/.local/share/mise/installs/python/3.12.7/bin/python

Or the shim:

~/.local/share/mise/shims/python

The shim re-resolves on each invocation, so it always picks the project-correct version.

Multiple Python versions (pyenv users often have many)

[tools]
python = "3.12 3.11 3.10"   # three versions, 3.12 is default

mise installs and makes all three available. python3.11 --version works; bare python resolves to the first.

Global tools (pipx / pip --user equivalents)

If you were using pip install --user black flake8 ruff or pipx, move to mise's pipx: backend:

# ~/.config/mise/config.toml
[tools]
python = "3.12"
"pipx:ruff" = "latest"
"pipx:black" = "latest"
"pipx:httpie" = "latest"

Version-pinned, managed, survives Python version upgrades (pipx detects and rebuilds).

Rollback

Reinstall pyenv if needed (your .python-version files are untouched):

curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash

Remove mise activation from shell rc. Restart shell.

See also

• mise-lang-python-overview — Python version resolution.
• mise-lang-python-packages — uv / poetry / pipx decision.
• mise-env-directives — _.python.venv auto-activation.
• mise-migrate-from-asdf — general migration shape.
• mise docs: mise.jdx.dev/faq.html#migrating-from-pyenv.
• python-build-standalone: github.com/astral-sh/python-build-standalone.