How to Fix pyenv's "No module named '_lzma'" Error
A pyenv-installed Python that raises this error is missing its lzma extension module:
ModuleNotFoundError: No module named '_lzma'The same problem also shows up as a warning when a library touches a .xz archive:
UserWarning: Could not import the lzma module. Your installed Python is incomplete.pyenv compiles Python from source. The standard library’s lzma module is a C extension that links against the external xz (liblzma) library, and that library has to be present when the interpreter is built. If it is missing, pyenv still finishes the build and prints only a warning, so the broken interpreter looks fine until something imports lzma.
Confirm the module is missing
Run the import directly against the affected interpreter:
$ python -c "import lzma"
Traceback (most recent call last):
File "<string>", line 1, in <module>
ModuleNotFoundError: No module named '_lzma'
A complete interpreter prints nothing and exits zero. The traceback confirms the build omitted _lzma.
Why installing xz alone does not fix it
_lzma is decided when pyenv compiles the interpreter. Installing xz afterward puts the library on the system, but the already-built Python was linked without it and does not pick it up. The interpreter has to be recompiled against the now-present library, which means uninstalling and reinstalling that version.
Rebuild the interpreter with xz present
Install the xz development files, then reinstall the affected Python version so pyenv recompiles against them.
Install xz with Homebrew:
brew install xzReinstall the affected version (substitute your own):
pyenv uninstall 3.12.0
pyenv install 3.12.0Confirm the rebuilt interpreter imports lzma:
$ python -c "import lzma"
No output means the module is back.
The same build-dependency trap hits other extension modules: readline (line editing), sqlite3, bz2, and ssl all go silently missing when their libraries are absent at compile time. pyenv’s suggested build environment lists every dependency to install before building.
Point the build at xz when it still fails
If pyenv install still omits _lzma after installing xz on macOS, Homebrew may have placed the library where the compiler does not look by default. Export the paths so the build finds it, then reinstall:
export LDFLAGS="-L$(brew --prefix xz)/lib"
export CPPFLAGS="-I$(brew --prefix xz)/include"
export PKG_CONFIG_PATH="$(brew --prefix xz)/lib/pkgconfig"
pyenv install 3.12.0brew --prefix xz expands to the installed location (/opt/homebrew/opt/xz on Apple Silicon, /usr/local/opt/xz on Intel), so the same commands work on both architectures.
Skip source compilation with uv
The failure exists because pyenv builds Python from source and depends on the right system libraries being present. uv removes that step. It downloads prebuilt python-build-standalone interpreters that already include lzma, sqlite3, readline, and the other extension modules, so there is nothing to compile and nothing to get wrong:
$ uv python install 3.12
Installed Python 3.12.7 in 646ms
The resulting interpreter is complete on the first try. See how to install Python with uv for the full command set, and how to switch from pyenv to uv to move version management over entirely.
Note
pyenv proper runs only on macOS and Linux. This build failure is a source-compilation issue that does not apply to pyenv-win, which installs official prebuilt Python binaries on Windows.