mise-en-place

Appearance

Python ​

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

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:

sh
mise use -g [email protected]

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

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

See the Python Cookbook for common tasks and examples.

.python-version support ​

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

Automatic virtualenv activation ​

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

toml
[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
# Install seed packages (pip, setuptools, and wheel) into the virtual environment.
_.python.venv = { path = ".venv", create = true, uv_create_args = ['--seed'] }

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

mise & uv ​

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

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

See the mise + uv Cookbook for more examples.

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:

text
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.

Installing free-threaded python ​

Free-threaded python can be installed via python-build 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 normally use Homebrew and you see errors regarding OpenSSL, your best bet might be using the following command to install Python:

sh
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).

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

Thus the entire script would look like:

sh
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 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(colon separated)
  • 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(colon separated)
  • 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.

Licensed under the MIT License. Maintained by @jdx and friends.

Copyright © 2025 @jdx