Mise Version Manager

There is no AI here. All content is human-authored and tested for accuracy.

Python with Mise

Mise simplifies Python version management on Mac, replacing Python's pyenv with a single tool for multiple languages. Use Mise to install and switch between Python versions, manage virtual environments automatically, and use mise with uv for comprehensive package management.

Mise is a multi-language version manager that handles Python, Node.js, Ruby, Java, and more from a single command line tool and configuration file. Mise unifies version management across your development environment with built-in virtual environment management. See Mise on Mac to understand how mise works and why developers switch from language-specific managers. For a broader overview of Python installation options on Mac, see Python on Mac.

Managing Python versions is one step in setting up your Mac for development. See the full roadmap to set up a Mac for development.

Before you get started

You'll need a terminal application to install and use the mise version manager for Python. Apple includes the Mac terminal but I prefer Warp Terminal. Warp is an easy-to-use terminal application, with AI assistance to help you learn and remember terminal commands. Download Warp Terminal now; it's FREE and worth a try.

First steps for Python with Mise

If you haven't installed mise yet, see the Install Mise on Mac guide. Verify that mise is working by running mise --version in your terminal. You should also run mise doctor after installation to ensure mise is activated by the ~/.zshrc file and shell hooks load correctly. This allows mise to automatically switch Python versions and activate virtual environments when you enter directories with a .mise.toml or .python-version file.

Set a global Python version

To set a default Python version for your entire system, run mise use with the --global flag. This version applies whenever you're in a directory without a .mise.toml file.

$ mise use --global [email protected]

The global version is stored in ~/.config/mise/config.toml. You can have multiple project-specific versions and still maintain a system-wide default. Mise downloads the latest precompiled Python binary and installs it to ~/.local/share/mise/installs/python/.

Project configuration files

You'll need a .mise.toml file in your project root to specify the exact Python version your project requires. This file enables automatic version switching: whenever you navigate into the project directory, mise activates the configured version. Commit this file to version control so your team uses identical Python versions. See Mise Configuration on Mac for other settings including environment variables, virtual environments, automated tasks, and advanced setup.

Existing projects with Mise for Python

If you have an existing Python project, you can use mise edit to create a .mise.toml configuration file. Instead of writing a file by hand, mise edit launches a terminal-based interactive editor (a TUI) that knows the structure of mise configuration and auto-detects language runtimes from your project files (reading requires-python from pyproject.toml), so existing projects get a pre-populated configuration with no manual work.

New projects with Mise for Python

If you are starting a new Python project, open your terminal application and navigate to your project directory. Run the command mise use to install the latest Python version.

$ mise use python

If you haven't installed a global Python version yet, Mise downloads the latest precompiled Python binary and installs it to ~/.local/share/mise/installs/python/. The command creates a .mise.toml file in your current directory with the installed version.

The configuration file is simple:

[tools]
python = "latest"

Verify the installation by checking the Python version and confirming pip is available.

$ python --version
$ pip --version

Both commands should display version numbers. The pip tool is bundled with your Python installation.

Install a specific Python version

If your project requires a particular major or minor version, use fuzzy matching to let mise select the latest patch version.

$ mise use [email protected]

This installs the latest Python 3.14.x version. To pin an exact version, use the --pin flag.

$ mise use --pin [email protected]

The --pin flag records the complete version string in .mise.toml, ensuring consistent behavior across your team.

Discover available Python versions

Before installing, you can browse all available Python versions using mise ls-remote python. This command shows every version available for installation.

$ mise ls-remote python

The output lists versions from oldest to newest. You can filter by major version to see all releases within a series.

$ mise ls-remote [email protected]

This shows every 3.14.x release available, helping you choose appropriate versions.

Choose the right Python version

Python 3.8 reached end-of-life in late 2024 and should not be used for new projects. Current development uses Python 3.13 or 3.14.

Handle .python-version files

If you're migrating from pyenv or have projects using .python-version files, mise reads them automatically. No conversion is necessary.

Mise recognizes several legacy version file formats without any configuration:

  • .python-version (pyenv format)
  • .tool-versions (asdf format)

When mise finds any of these files, it automatically switches to the specified version upon entering the directory. To ensure .python-version compatibility is fully enabled, run this command once.

$ mise settings add idiomatic_version_file_enable_tools python

This enables automatic version switching for all version file formats. After running this, your existing pyenv setups work seamlessly with mise. But you might want to use a .mise.toml file because it gives you more options, as described in Mise Configuration.

Migrate from pyenv to mise

If you currently use pyenv, switching to mise takes just a few steps. Your existing Python installations don't need to be reinstalled immediately.

You can install Python globally with mise use -g [email protected] (using the -g flag) or install Python versions with mise in each of your projects:

$ mise use [email protected]

Then comment out the pyenv initialization lines in your shell configuration file. If you use zsh, open ~/.zshrc and find lines that source pyenv (usually near the end). Comment them out or delete them, then save the file.

After restarting your terminal, mise handles Python version management instead of pyenv. Your existing .python-version files work automatically with mise.

Switch between Python versions per project

One of mise's most powerful features is automatic version switching. When you navigate into a project directory with a .mise.toml or .python-version file, mise automatically switches to that project's Python version.

Create two project directories with different Python versions to see this in action. In the first project, create a .mise.toml specifying Python 3.14.

$ cd project-a/
$ mise use [email protected]
$ python --version
Python 3.14.x

Create a second project directory and install Python 3.11.

$ cd ../project-b/
$ mise use [email protected]
$ python --version
Python 3.11.x

Now navigate back to project-a. Mise automatically switches the version.

$ cd ../project-a/
$ python --version
Python 3.14.x

This automatic switching happens whenever you enter a directory containing version specifications, making it impossible to accidentally use the wrong Python version.

Follow best practices for Python versions

When managing Python versions across your projects, follow these practices to prevent conflicts and maintain consistency.

Always specify Python versions in .mise.toml for projects you plan to share with others or maintain long-term. This ensures new team members and future versions of yourself use identical configurations.

Use exact version pinning for production projects. The --pin flag creates reproducible builds across environments.

$ mise use --pin [email protected]

Keep your global Python version at a reasonable stable release that matches your most common work. This provides a sensible fallback when you're outside project directories.

Regular updates to Python versions are important for security. Patch releases address vulnerabilities. See Update Python on Mac for guidance on keeping Python current. Review Python release notes before updating to new major versions, as breaking changes sometimes require code updates.

Use different Python versions for different tasks

Advanced workflows sometimes require different Python versions for different purposes. Mise supports executing specific commands with non-default versions.

Use mise exec to run a single command with a specific Python version without changing your default.

$ mise exec [email protected] -- python --version
Python 3.11.x

This approach is useful for testing compatibility with older versions or running tools that require specific Python versions without permanently switching.

Verify your setup

After configuring mise for Python, verify the setup is complete and working correctly.

Check that mise is recognizing your .mise.toml configuration.

$ mise current python

This displays the current Python version mise is using. It should match your .mise.toml specification.

Virtual environments

Python requires virtual environments to manage dependencies on a per-project basis. Languages such as Node.js and Ruby handle project-level dependencies natively (with node_modules and Bundler, respectively), but Python installs packages globally by default. Recent macOS versions enforce an externally managed environment restriction that blocks global pip installs, making virtual environments essential. Without a virtual environment, installing a package for one project can break another. Mise makes virtual environments easier to use by keeping the Python version and the .venv directory in sync for each project.

The key rule is simple: let mise choose the Python version first, then create a .venv inside the project directory.

Use uv for virtual environments (recommended)

You can use the uv package manager to install Python and manage dependencies. If you are using mise to manage multiple languages, you don't need to use uv to install Python. But mise is not a package manager (used to install software libraries as project dependencies), and uv is great for package management, so I recommend to use mise with uv, each for what they do best.

The uv package manager creates virtual environments faster than Python's built-in venv module and provides dependency resolution with lock files. Python has historically lacked lock files for dependencies (until PEP751 was accepted in 2025) and uv addresses this gap.

Install uv with mise on a per-project basis if you do not already have it. See Install uv on Mac for a full guide.

$ mise use uv

Or you can install uv globally with the -g flag.

$ mise use -g uv

In a new Python project, after setting the Python version with mise use [email protected], create a virtual environment with uv.

$ uv venv .venv

This creates a .venv directory tied to the Python version mise selected. Activate it and install dependencies.

$ source .venv/bin/activate
$ uv pip install -r requirements.txt

Commands such as python and pip now use the isolated .venv environment. Alternatively, skip manual activation entirely by running commands through uv.

$ uv run script.py

The uv run command activates the virtual environment transparently, so you never need to run source .venv/bin/activate yourself.

See below for how to set up automatic virtual environments.

Use plain venv as an alternative

If you don't want to use uv, Python includes a built-in venv module that works without installing uv. After setting the Python version with mise use [email protected], create the environment.

$ python -m venv .venv

Activate the environment and install dependencies with pip.

$ source .venv/bin/activate
$ pip install -r requirements.txt

This approach works on any system with Python. It does not provide dependency resolution or lock files, but it gives you clean isolation per project. If you upgrade the Python version for a project, delete the old venv and recreate it so all packages are built against the correct version.

$ rm -rf .venv
$ python -m venv .venv
$ pip install -r requirements.txt

Set up automatic virtual environments

Mise can create and activate virtual environments automatically when you enter a project directory. This eliminates manual setup and activation.

If you use uv (recommended), add this configuration to your .mise.toml file.

[_.python]
venv = ".venv"
uv_venv_auto = "create|source"

The uv_venv_auto setting tells mise to use uv for creating the virtual environment. When you navigate to the project, mise creates .venv if it does not exist and activates it automatically.

If you do not use uv, configure mise with the built-in venv module instead.

[_.python]
venv = ".venv"
virtual_env_auto_create = true

Both configurations eliminate the need to run source .venv/bin/activate manually. The virtual environment activates whenever you enter the directory.

Compare Mise and uv for Python

Mise and uv serve different purposes in Python development and work well together. Understanding their roles prevents confusion about which tool to use.

Mise is a version manager. It handles Python version selection and virtual environment management. Mise does not install packages, resolve dependencies, or manage lock files.

The tool uv is a package and project manager. It replaces pip, pip-tools, and pipx for package installation. Uv provides fast dependency resolution, lock files, and project scaffolding. Uv also includes Python version management as an alternative to pyenv, if you are not using mise.

Decide when to use each tool

In a project using both tools, mise handles Python versions and uv handles packages.

Use mise when you need:

  • Managing multiple languages with consistent commands
  • Multi-language projects (mixing Python with Node.js, Ruby, etc.)
  • Version management across multiple Python projects
  • Automatic version switching on directory entry
  • Team consistency through committed .mise.toml files

Use uv when you need:

  • Fast package installation
  • Dependency resolution and lock files
  • Virtual environment management specific to a project
  • Faster alternative to pip and virtualenv

For most projects, use mise to manage the Python version and uv to manage packages. This division of responsibility is clean and efficient.

Set up a workflow with mise and uv

In your project directory, configure mise for Python version management.

$ mise use [email protected]

Install uv and then use uv for package installation and management.

$ mise use uv
$ uv add requests pandas
$ uv run script.py

The workflow is straightforward. Mise ensures you're using Python 3.14 in this directory. The tool uv handles packages and runs Python scripts within the project's environment.

Handle virtual environments with uv

The tool uv manages virtual environments automatically through its uv run command. When you run uv run script.py, the tool activates the project's venv transparently. You never manually activate environments with uv.

Mise can create and activate virtual environments, but uv takes this further by integrating venv activation directly into command execution. If you use uv extensively, rely on its venv management. If you prefer mise's directory-entry activation, use mise's venv configuration.

Both approaches work together. Mise can detect uv's virtual environment through configuration, and uv respects the Python version mise sets.

Python build dependencies

Mise defaults to downloading precompiled Python binaries, so build dependencies are typically unnecessary. For most developers on Apple Silicon (M-series), precompiled binaries work perfectly. Precompiled binaries install 10-50 times faster than compilation and eliminate common build errors.

Build dependencies are required only in these scenarios:

  • You explicitly disable precompiled binaries
  • A precompiled binary is unavailable for your Python version or architecture
  • You're using a very recent or very old Python version without binary support

If you need to compile Python from source, install these Homebrew packages. As an alternative to compiling, you can install Python with Homebrew for a simpler single-version setup.

$ brew install openssl@3 libffi libyaml

These packages provide essential libraries for Python compilation. The openssl@3 package is critical for SSL/TLS support in many Python libraries.

If you compile Python and encounter OpenSSL errors, configure the compiler to locate your Homebrew installation.

$ export CFLAGS="-I$(brew --prefix openssl)/include"
$ export LDFLAGS="-L$(brew --prefix openssl)/lib"
$ mise install [email protected]

These environment variables tell the Python build system where OpenSSL is located, resolving configuration errors.

Troubleshoot Python issues

If version switching isn't working, verify that mise's shell hooks are loaded. Restart your terminal completely (close all tabs) to ensure the latest shell configuration is loaded. Run mise doctor for diagnostics to ensure mise is activated by the ~/.zshrc file.

Check that .mise.toml exists in your project directory and contains valid configuration.

$ cat .mise.toml

The file should have a [tools] section with python = "version". If the file is missing, run mise use python@version to create it.

If you see a "command not found" error for Python, see Fix Python command not found on Mac. If pip is not found, see Fix pip command not found on Mac.

If the virtual environment isn't activating automatically, verify the configuration includes venv settings.

[_.python]
venv = ".venv"
# for uv
uv_venv_auto = "create|source"
# for plain venv
virtual_env_auto_create = true

Use Python across your stack

Mise's true power emerges when managing multiple languages. If your project uses Python and Node.js, you can specify both in a single .mise.toml file.

[tools]
python = "3.14"
node = "24"

When you enter this directory, both versions activate automatically. This single-file approach eliminates tool switching and makes your project setup reproducible.

For web applications using Python alongside JavaScript, this multi-language approach keeps your entire development environment synchronized.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.