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
(optional) - Env:
MISE_PYTHON_PRECOMPILED_ARCH
- Default:
None
Specify the architecture to use for precompiled binaries.
python.precompiled_os
- Type:
string
(optional) - Env:
MISE_PYTHON_PRECOMPILED_OS
- Default:
None
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.venv_auto_create
deprecated
- Type:
Bool
- Env:
MISE_PYTHON_VENV_AUTO_CREATE
- Default:
false
- Deprecated: Use env._python.venv instead.
Automatically create virtualenvs for python tools.
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
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=1 PYTHON_BUILD_FREE_THREADING=1 mise install
Currently, they are not supported with precompiled binaries.