How to Set Up Python 3.13t (Free-Threaded Build) Using mise on macOS Sonoma

Python 3.13 introduces experimental free-threaded builds (python3.13t), with the Global Interpreter Lock (GIL) disabled via PEP 703. This enables true parallelism in multithreaded code—particularly useful for CPU-bound tasks in AI/ML workloads and high-performance computing on macOS Sonoma (14.x) Apple Silicon Macs. Mise is a fast, Rust-based version manager that works well with Python installations. In this guide, we’ll walk through the setup process using mise.

Related: Migrate from pyenv to mise, mise vs asdf benchmarks.

Why Python 3.13t Free-Threaded on macOS Sonoma?

• No GIL: Threads run in parallel on multi-core Apple M-series chips.
• Performance: Potential speedups of up to 2x in multithreaded applications (e.g., NumPy, PyTorch).
• Future-proof: Experimental in 3.13, stabilizing soon.
• Mise advantages: Auto .tool-versions, tasks, direnv integration.

Tested on Sonoma 14.7+ with M1/M2/M3.

Prerequisites

• macOS Sonoma (14.x).
• Xcode Command Line Tools: $ xcode-select --install.
• Homebrew: $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)".
• Terminal (iTerm2/Zsh recommended).

Step 1: Install mise (if needed)\n\nIf mise isn’t installed, run these commands:\n\nbash\n$ curl https://mise.run | sh\n$ echo 'eval "$(mise activate zsh)"' >> ~/.zshrc # or ~/.bashrc\n$ exec $SHELL\n$ mise --version\n\n\nReload your shell and verify the installation. For details, see Step 2 in the migration guide.

Step 2: Install Build Dependencies via Homebrew\n\nSince Python 3.13t builds from source, install these libraries:\n\nbash\n$ brew install openssl readline sqlite3 xz zlib tcl-tk libffi\n

Add these exports to your ~/.zshrc (or equivalent):\n\nbash\n$ export LDFLAGS="-L$(brew --prefix openssl)/lib -L$(brew --prefix readline)/lib -L$(brew --prefix zlib)/lib -L$(brew --prefix sqlite3)/lib"\n$ export CPPFLAGS="-I$(brew --prefix openssl)/include -I$(brew --prefix readline)/include -I$(brew --prefix zlib)/include -I$(brew --prefix sqlite3)/include"\n

Step 3: Install Python 3.13t Free-Threaded\n\nFirst, list available versions:\n\nbash\n$ mise ls-remote python | grep 3.13t\n

Install latest (e.g., 3.13.0t):

bash\n$ mise install python@3.13.0t\n

Set global:

bash\n$ mise use --global python@3.13.0t\n

Per-project: Create .tool-versions with python 3.13.0t.

Step 4: Verify Installation\n\nCheck the version and build details:\n\nbash\n$ python --version # Python 3.13.0\n$ python -VV # ... experimental-jit free-threaded CPython\n

Python shell test:

import sys
import threading

print(sys._is_gil_enabled())  # False
print(threading.active_count())  # >1 possible

# Multithread test
import time
def worker(n):
    sum(range(n))
    return n

threads = [threading.Thread(target=worker, args=(10**7,)) for _ in range(8)]
start = time.time()
for t in threads: t.start()
for t in threads: t.join()
print(f"Time: {time.time() - start:.2f}s")  # Compare to standard Python 3.13 (with GIL)

Troubleshooting

• Build fails: Reinstall deps, check mise doctor. Set MISE_PYTHON_FORCE_UTF8=1.
• No 3.13t: Update mise: mise self update. Check mise Python plugin.
• Shims broken: mise reshim python.
• pip issues: python -m pip install --upgrade pip.
• Sonoma ARM: Ensure Rosetta not interfering (arch).

Performance Tips

• Libraries: NumPy/SciPy need free-threaded wheels (pip 24.2+).
• Benchmarks: See Python 3.13 free-threaded docs.
• Re-enable GIL: PYTHON_GIL=1 python.

Conclusion

You’ve now set up Python 3.13t free-threaded with mise on macOS Sonoma. As we covered, install the build dependencies, then mise install python@3.13.0t and verify GIL status with sys._is_gil_enabled(). This can improve multithreading performance in ML and scientific code. For more, see the mise documentation.

Key Takeaways:

• Free-threaded = no GIL, parallel threads.
• Mise: install python@3.13.0t, .tool-versions.
• Verify: python -VV, multithread test.