Python

The following are instructions for using the python mise core plugin. The core plugin will be used so long as no plugin is manually installed named "python" using mise plugins install python [GIT_URL].

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

Usage

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

mise use -g [email protected]

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

$ mise use -g [email protected] [email protected]
$ python -V
3.10.0
$ python3.11 -V
3.11.0

Settings

python-build already has a handful of settings, in additional to that 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: Bool(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

• Type: Path(optional)
• Env: MISE_PYTHON_DEFAULT_PACKAGES_FILE
• Default: None

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

python.patch_url

• Type: Url(optional)
• Env: MISE_PYTHON_PATCH_URL
• Default: None

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

python.patches_directory

• Type: Path(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: "apple-darwin" | "unknown-linux-gnu" | "unknown-linux-musl"

Specify the architecture to use for precompiled binaries.

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: "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.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: Bool
• Env: MISE_PYTHON_UV_VENV_AUTO
• Default: false

Integrate with uv to automatically create/source venvs if uv.lock is present.

python.uv_venv_create_args

• Type: string(optional)
• Env: MISE_PYTHON_UV_VENV_CREATE_ARGS
• Default: None

Arguments to pass to uv when creating a venv.

python.venv_auto_createdeprecated

• Type: Bool
• Env: MISE_PYTHON_VENV_AUTO_CREATE
• Default: false
• Deprecated: Use env._python.venv instead.

Automatically create virtualenvs for python tools.

python.venv_create_args

• Type: string(optional)
• Env: MISE_PYTHON_VENV_CREATE_ARGS
• Default: None

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

python.venv_stdlib

• Type: Bool
• Env: MISE_VENV_STDLIB
• Default: false

Prefer to use venv from Python's standard library.

Default Python packages

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

ansible
pipenv

You can specify a non-default location of this file by setting a MISE_PYTHON_DEFAULT_PACKAGES_FILE variable.

Precompiled python binaries

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

In addition to being faster, it also means you don't have to install all of the system dependencies either.

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

If you'd like to disable these binaries, set mise settings python.compile=1.

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

python-build

Optionally, mise uses python-build (part of pyenv) to compile python runtimes, you need to ensure its dependencies are installed before installing python with python-build.

Troubleshooting errors with Homebrew

If you normally use Homebrew and you see errors regarding OpenSSL, your best bet might be using the following command to install Python:

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 system-expected ones. You could even add that to your .profile, .bashrc, .zshrc... to avoid setting them every time

Additionally, if you encounter issues with python-build, you may benefit from unlinking pkg-config prior to install (reason).

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

Thus the entire script would look like:

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

Automatic virtualenv activation

Python comes with virtualenv support built in, use it with mise.toml configuration like one of the following:

[tools]
python = "3.11" # [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.10" } # 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

The venv will need to be created manually with python -m venv /path/to/venv unless create=true.

Installing free-threaded python

Free-threaded python can be installed via python-build by running the following:

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

Or to compile with python-build:

MISE_PYTHON_COMPILE=1 PYTHON_BUILD_FREE_THREADING=1 mise install python