Python

Like pyenv, mise can manage multiple versions of Python on the same system. It can also automatically create virtual environments for your projects and integrates with uv.

The following are instructions for using the python mise core plugin. It is used when no plugin named "python" has been installed manually with mise plugins install python [GIT_URL].

The code for this is inside the mise repository at ./src/plugins/core/python.rs.

Usage

The following installs the latest version of python-3.15.x and makes it the global default:

mise use -g python@3.15

You can also use multiple versions of python at the same time:

$ mise use -g python@3.14 python@3.15
$ python -V
3.14.0
$ python3.15 -V
3.15.0

You can also install a specific python flavour. To get the latest version of a flavour, use the flavour prefix alone:

mise use -g python@anaconda         # latest version of anaconda

See the Python Cookbook for common tasks and examples.

Tool Options

The following tool-options are available for the python backend. These options go in the [tools] section in mise.toml.

`install_env`

Set environment variables for python-build, default package installation, and install-time verification commands run by the core python backend:

toml

[tools]
python = { version = "latest", install_env = { CONFIGURE_OPTS = "--enable-optimizations" } }

`patch_sysconfig`

When installing precompiled Python binaries on Unix, mise patches the Python sysconfig data by default so build-time paths from python-build-standalone point at the final mise install path. If that patching causes an install problem for a specific Python build, disable it with patch_sysconfig = false:

toml

[tools]
python = { version = "3.14", patch_sysconfig = false }

Disabling this patch can leave stale build-time paths in the installed Python's sysconfig data, so prefer the default unless you need this as an install workaround.

`.python-version` support

.python-version/.python-versions files are supported by mise. See idiomatic version files.

Automatic virtualenv activation

mise has two ways to manage Python virtualenvs:

Mechanism	Best for	Config location
`python.uv_venv_auto`	uv projects (with `uv.lock`)	`[settings]` section
`_.python.venv`	Projects not using uv	`[env]` section

python.uv_venv_auto detects and sources the virtual environment managed by uv (.venv by default, or the path configured by UV_PROJECT_ENVIRONMENT). Use "source" to activate only existing venvs, or "create|source" to create the venv if it is missing. mise locates the uv project by walking up for a uv.lock file, so a uv.lock must be present — without one the setting does nothing. See the mise + uv Cookbook for full examples.

_.python.venv creates/activates a venv and adds it to PATH. It works with both mise activate and mise exec. Use this for projects that don't use uv.

WARNING

These are separate mechanisms with different code paths. Options like uv_create_args and python_create_args in _.python.venv are not used by python.uv_venv_auto.

WARNING

The legacy virtualenv tool option (python = { version = "3.15", virtualenv = ".venv" } in [tools]) is deprecated and will be removed in a future release. Use _.python.venv (below) instead.

`_.python.venv` configuration

Use _.python.venv in the [env] section of mise.toml:

toml

[tools]
python = "3.15" # [optional] will be used for the venv

[env]
_.python.venv = ".venv" # relative to this file's directory
_.python.venv = "/root/.venv" # can be absolute
_.python.venv = "{{env.HOME}}/.cache/venv/myproj" # can use templates
_.python.venv = { path = ".venv", create = true } # create the venv if it doesn't exist
_.python.venv = { path = ".venv", create = true, python = "3.15" } # use a specific python version
_.python.venv = {
  path = ".venv", create = true,
  python_create_args = ["--without-pip"], # pass args to python -m venv
}
_.python.venv = {
  path = ".venv", create = true,
  uv_create_args = ["--system-site-packages"], # pass args to uv venv
}
# Install seed packages (pip, setuptools, and wheel) into the virtual environment.
_.python.venv = { path = ".venv", create = true, uv_create_args = ['--seed'] }

Unless create=true is set, you need to create the venv manually with python -m venv /path/to/venv. See env-directives for _.python.venv.

TIP

Virtualenv activation requires mise activate or mise exec. When using shims alone, the venv's bin/ directory is not added to PATH, so which python will point to the shim rather than the venv's interpreter.

`python.uv_venv_auto` setting

For uv-managed projects (those with a uv.lock file), you can use the python.uv_venv_auto setting to automatically source or create the virtual environment that uv manages. mise finds the project root by walking up for a uv.lock; that lockfile is how mise knows the project uses uv, so one must be present. If no uv.lock is found, the setting is a no-op — run uv sync (or uv lock) to generate one first. See the mise + uv Cookbook for full examples.

mise.toml

toml

[settings]
python.uv_venv_auto = "source"        # activate existing .venv
# or
python.uv_venv_auto = "create|source" # create .venv if missing, then activate

mise respects uv's UV_PROJECT_ENVIRONMENT variable when choosing the environment path. A relative path is resolved from the uv project root (the directory containing uv.lock), while an absolute path is used as-is. When the variable is unset or empty, mise uses .venv.

mise.toml

toml

[env]
UV_PROJECT_ENVIRONMENT = "my.venv"

[settings]
python.uv_venv_auto = "create|source"

mise & uv

If you have installed uv (for example, with mise use -g uv@latest), mise will use it to create virtual environments via _.python.venv. Otherwise, it will use the built-in python -m venv command.

uv does not include pip by default (it provides uv pip instead). If you need the pip package, add the uv_create_args = ['--seed'] option.

WARNING

The true value for python.uv_venv_auto is legacy and has been deprecated since mise 2026.7, which warns whenever it is used; support for it is scheduled to be removed in mise 2027.7. Prefer "source" or "create|source". The python.uv_venv_auto setting itself is not going away — only the true value is being phased out.

One difference between the legacy true value and the newer string values is that true also exports UV_PYTHON (set to only the Python version number). This tells uv which Python version to use, but does not guarantee that uv uses the specific interpreter managed by mise — uv may fall back to a system or self-managed Python of the same version.

To ensure uv uses the Python interpreter managed by mise, set UV_PYTHON to the actual install path instead:

toml

[tools]
python = "3.15"

[env]
UV_PYTHON = { value = "{{ tools.python.path }}", tools = true }

See the mise + uv Cookbook for more examples.

Default Python packages

Planned deprecation

Default package files are deprecated. They are still supported for now, but mise will start warning in 2026.11.0 and support will be removed in 2027.11.0.

For Python CLIs, install the tool directly with the pipx backend:

toml

[tools]
"pipx:black" = "latest"

For packages that really should be installed into every Python version, use a tool-level postinstall hook:

toml

[tools]
python = { version = "3.13", postinstall = "python -m pip install --upgrade ansible" }

mise can automatically install a default set of Python packages with pip right after installing a Python version. To use this legacy feature, provide a $HOME/.default-python-packages file that lists one package per line, for example:

text

ansible
pipenv

You can specify a different location for this file with the MISE_PYTHON_DEFAULT_PACKAGES_FILE variable.

Precompiled python binaries

By default, mise downloads precompiled binaries for python instead of compiling them with python-build. This makes installing python much faster.

It also means you don't have to install the system dependencies needed to compile python.

That said, there are some quirks with the precompiled binaries to be aware of.

To disable these binaries, run mise settings python.compile=1.

These binaries may not work on older CPUs. You can opt into binaries that are more compatible with older CPUs by setting MISE_PYTHON_PRECOMPILED_ARCH to a different value; set it to "x86_64" for the most compatible binaries. See https://gregoryszorc.com/docs/python-build-standalone/main/running.html for more information on this option.

Windows

mise uses the same precompiled python-build-standalone binaries on Windows (compiling with python-build is not supported there). Two of the upstream quirks are smoothed over by mise:

The archives only ship python.exe, so mise creates a python3.exe alias next to it.
The archives ship no pip.exe (pip is only available as python -m pip), so mise creates pip.cmd/pip3.cmd wrappers in the install root that delegate to python -m pip. Because they delegate, they keep working even after pip upgrades itself.

The install's Scripts directory is included in PATH, so console scripts from pip install (e.g. black) are runnable. If you rely on shims instead of mise activate, run mise reshim after pip install to generate shims for newly installed executables.

python-build

Optionally, mise can use python-build (part of pyenv) to compile python runtimes. Make sure its dependencies are installed before installing python with python-build.

Installing free-threaded python

Free-threaded python can be installed from precompiled binaries by running the following:

bash

MISE_PYTHON_COMPILE=0 MISE_PYTHON_PRECOMPILED_FLAVOR=freethreaded+pgo-full mise install python

Or to compile with python-build:

bash

MISE_PYTHON_COMPILE=1 PYTHON_BUILD_FREE_THREADING=1 mise install python

Troubleshooting errors with Homebrew

If you use Homebrew and see errors regarding OpenSSL, try installing Python with the following command:

CFLAGS="-I$(brew --prefix openssl)/include" \
LDFLAGS="-L$(brew --prefix openssl)/lib" \
mise install python@latest;

Homebrew installs its own OpenSSL version, which may collide with the one the system expects. You could add these variables to your .profile, .bashrc, or .zshrc to avoid setting them every time.

If you encounter issues with python-build, you may also benefit from unlinking pkg-config before installing (reason):

brew unlink pkg-config
mise install python@latest
brew link pkg-config

The entire script would then look like this:

brew unlink pkg-config
CFLAGS="-I$(brew --prefix openssl)/include" \
  LDFLAGS="-L$(brew --prefix openssl)/lib" \
  mise install python@latest
brew link pkg-config

Settings

python-build already has a handful of settings; in addition, python in mise has a few extra configuration variables.

Set these with mise settings set [VARIABLE]=[VALUE] or by setting the environment variable.

`python.compile`

Type: boolean(optional)
Env: MISE_PYTHON_COMPILE
Default: None

Values:
- true - always compile with python-build instead of downloading precompiled binaries.
- false - always download precompiled binaries.
- [undefined] - use precompiled binary if one is available for the current platform, compile otherwise.

`python.default_packages_file`deprecated

Type: string(optional)
Env: MISE_PYTHON_DEFAULT_PACKAGES_FILE
Default: None
Deprecated: Default python package files are deprecated. Use tool-level postinstall hooks for packages that should be installed into every python version, or use the pipx: backend for CLI tools.

Path to a file containing default python packages to install when installing a python version.

`python.github_attestations`

Type: boolean(optional)
Env: MISE_PYTHON_GITHUB_ATTESTATIONS
Default: None

Override the global github_attestations setting for Python precompiled binaries. When enabled, mise will verify the authenticity of precompiled Python binaries from astral-sh/python-build-standalone.

Defaults to the global github_attestations setting if not specified.

`python.patch_url`

Type: string(optional)
Env: MISE_PYTHON_PATCH_URL
Default: None

URL to fetch python patches from to pass to python-build.

`python.patches_directory`

Type: string(optional)
Env: MISE_PYTHON_PATCHES_DIRECTORY
Default: None

Directory to fetch python patches from.

`python.precompiled_arch`

Type: string
Env: MISE_PYTHON_PRECOMPILED_ARCH
Default: "x86_64_v3" | "aarch64"

Specify the architecture to use for precompiled binaries. If on an old CPU, you may want to set this to "x86_64" for the most compatible binaries. See https://gregoryszorc.com/docs/python-build-standalone/main/running.html for more information.

`python.precompiled_flavor`

Type: string
Env: MISE_PYTHON_PRECOMPILED_FLAVOR
Default: install_only_stripped

Specify the flavor to use for precompiled binaries.

Options are available here: https://gregoryszorc.com/docs/python-build-standalone/main/running.html

`python.precompiled_os`

Type: string
Env: MISE_PYTHON_PRECOMPILED_OS
Default: "apple-darwin" | "unknown-linux-gnu" | "unknown-linux-musl"

Specify the OS to use for precompiled binaries.

`python.pyenv_repo`

Type: string
Env: MISE_PYENV_REPO
Default: https://github.com/pyenv/pyenv.git

URL to fetch pyenv from for compiling python with python-build.

`python.uv_venv_auto`

Type: boolean | string
Env: MISE_PYTHON_UV_VENV_AUTO
Default: false
Choices:
- false – disable uv venv integration
- source – only source an existing .venv
- create|source – create the venv if missing and source it
- true – (create|source) with UV_PYTHON export (deprecated)

Controls how mise handles uv project venvs when a uv.lock file is present.

The legacy true value is deprecated: it warns since mise 2026.7.0 and will be removed in mise 2027.7.0. It is treated like "create|source", with one difference: mise also exports UV_PYTHON to force uv to use the python version managed by mise. Prefer "source" or "create|source".

`python.uv_venv_create_args`

Type: string[](optional)
Env: MISE_PYTHON_UV_VENV_CREATE_ARGS(colon separated)
Default: None

Arguments to pass to uv when creating a venv.

`python.venv_create_args`

Type: string[](optional)
Env: MISE_PYTHON_VENV_CREATE_ARGS(colon separated)
Default: None

Arguments to pass to python when creating a venv. (not used for uv venv creation)

`python.venv_stdlib`

Type: boolean
Env: MISE_VENV_STDLIB
Default: false

Prefer to use venv from Python's standard library.

Python ​

Usage ​

Tool Options ​

install_env ​

patch_sysconfig ​

.python-version support ​

Automatic virtualenv activation ​

_.python.venv configuration ​

python.uv_venv_auto setting ​

mise & uv ​

Default Python packages ​

Precompiled python binaries ​

Windows ​

python-build ​

Installing free-threaded python ​

Troubleshooting errors with Homebrew ​

Settings ​

python.compile

python.default_packages_filedeprecated

python.github_attestations

python.patch_url

python.patches_directory

python.precompiled_arch

python.precompiled_flavor

python.precompiled_os

python.pyenv_repo

python.uv_venv_auto

python.uv_venv_create_args

python.venv_create_args

python.venv_stdlib

Python

Usage

Tool Options

`install_env`

`patch_sysconfig`

`.python-version` support

Automatic virtualenv activation

`_.python.venv` configuration

`python.uv_venv_auto` setting

mise & uv

Default Python packages

Precompiled python binaries

Windows

python-build

Installing free-threaded python

Troubleshooting errors with Homebrew

Settings

`python.compile`

`python.default_packages_file`deprecated

`python.github_attestations`

`python.patch_url`

`python.patches_directory`

`python.precompiled_arch`

`python.precompiled_flavor`

`python.precompiled_os`

`python.pyenv_repo`

`python.uv_venv_auto`

`python.uv_venv_create_args`

`python.venv_create_args`

`python.venv_stdlib`