The CRITICAL distinction between system packages (apt/brew/dnf — libssl, libpq, build-essential) and dev tools (mise — node, python, cmake, ripgrep). The
mise installs dev tools. apt/brew/dnf install system packages.
| Use mise for | Use apt/brew/dnf for |
|---|---|
Language runtimes (node, python, go, ruby, rust, java) | System libraries (libssl, libpq-dev, libxml2, zlib) |
Build tools (cmake, ninja, bazel, meson) | Compilers (gcc, g++, clang) — usually system |
Static analysis (clang-tidy, eslint, ruff, shellcheck) |
Build essentials (build-essential, make) |
Formatters (prettier, black, clang-format, stylua) | Kernel headers, drivers |
CLI utilities (ripgrep, fd, gh, jq, bat) | System services (postgres, redis, nginx) for local dev |
Cloud tools (terraform, kubectl, aws-cli, gcloud) | GUI applications (vscode, docker-desktop) |
Package managers for languages (pipx, uv, poetry, pnpm, yarn, conan) | Filesystem tools (fuse, cifs-utils) |
Many language runtimes need to compile against system libraries. Python is the canonical example — when mise compiles Python from source (or even uses some prebuilt binaries), it dynamically links against:
libssl / libcrypto (for the ssl module)libffi (for ctypes)libsqlite3 (for the sqlite3 module)liblzma (for lzma)libreadline / libedit (for the REPL)zlib (for the zlib module)If those system libraries aren't installed, mise will install Python successfully and then import ssl will crash at runtime. This is the most common newbie complaint.
The fix is not "install libssl with mise" (impossible — mise doesn't install system libs). The fix is install libssl with apt/brew first, then re-run mise install python.
sudo apt update
sudo apt install -y \
build-essential \
curl git ca-certificates \
libssl-dev libffi-dev libsqlite3-dev liblzma-dev libreadline-dev libbz2-dev \
zlib1g-dev libncursesw5-dev libxml2-dev libxmlsec1-dev tk-dev xz-utils \
pkg-config
This is enough to compile Python, Ruby, Erlang, Elixir, and most other languages mise installs from source.
xcode-select --install # provides clang, make, headers
brew install openssl@3 readline sqlite3 xz libffi
For most users, just xcode-select --install is enough — modern mise prefers prebuilt Python binaries that bundle their own deps.
sudo dnf groupinstall "Development Tools"
sudo dnf install openssl-devel libffi-devel sqlite-devel xz-devel readline-devel bzip2-devel zlib-devel
⚠️ Alpine uses musl libc, not glibc. Many mise tools ship glibc-only binaries that won't run on Alpine. Stick with debian:slim or ubuntu base images for mise-based Docker workflows.
If you must use Alpine:
apk add --no-cache build-base curl bash git openssl-dev libffi-dev sqlite-dev xz-dev readline-dev bzip2-dev zlib-dev
And expect to compile from source for most tools.
mise prefers precompiled binaries with provenance when available (e.g., core:python uses precompiled Python from python-build-standalone). These are statically linked or bundle their own deps, so the system libs above matter less.
When mise falls back to compiling from source (e.g., for older Python versions, Ruby, Erlang), the system libs become critical.
To force precompiled where possible:
[settings]
python.compile = false # use precompiled python (default behavior in recent mise)
ruby.compile = false # same for ruby
| Symptom | Likely missing |
|---|---|
ImportError: No module named '_ssl' (Python) | libssl-dev |
ImportError: ... '_sqlite3' | libsqlite3-dev |
ImportError: ... '_lzma' | liblzma-dev / xz-dev |
make: gcc: command not found | build-essential / Xcode CLT |
cannot find -lz during compile | zlib1g-dev |
error: openssl/ssl.h: No such file | libssl-dev |
Ruby Failed to build gem ... | depends, often libreadline-dev or libyaml-dev |
| Erlang/Elixir compile errors | libssl-dev, libncurses5-dev, libwxgtk*-dev |
mise: tool failed to install with vague "compile error" | almost always missing system libs |
apt install libssl-dev ... THEN curl https://mise.run | sh THEN mise install.For C++ developers, gcc/clang/make/cmake are interesting cases:
gcc / clang: usually system. apt install gcc g++ or brew install gcc llvm. mise CAN install gcc/clang via aqua but it's unusual.cmake: ✅ mise. Pin per-project via aqua:Kitware/CMake. Better than the system cmake which is often outdated.ninja: ✅ mise.ccache: ✅ mise.clang-format / clang-tidy: ✅ mise (locked formatter version = no PR formatting drift). Or use the system clang's tools — both fine.conan / vcpkg: ✅ mise (conan via pipx:conan; vcpkg as a git submodule, mise can manage the bootstrap task).See the v0.4 mise-cookbook-cpp skill for the full C++ recipe.
psql CLI (via aqua/github).apt install -y build-essential libssl-dev ... BEFORE mise install in your CI script or Dockerfile./mise-install command — installs mise itself, mentions prerequisitesmise-deployment-models — Docker base images that handle prerequisitesmise-troubleshooting — diagnostic flow for tool install failures