ModuleNotFoundError: No Module Named ‘_lzma’

ModuleNotFoundError: No module named '_lzma' is not a missing pip package. The leading underscore means it is a C extension that ships with Python — and yours was compiled on a machine that did not have the LZMA development library installed. The fix is to install that library and rebuild Python, not to install anything from PyPI.

Where it comes from#

ModuleNotFoundError: No module named '_lzma'

Often it appears indirectly, from pandas reading a compressed file, or from tarfile handling an .xz archive:

import pandas as pd
df = pd.read_csv("data.csv.xz")     # triggers it

Sometimes it arrives as a warning at import time and only becomes an error later, which makes it easy to miss the real cause.

Why pip cannot help#

Modules whose names start with an underscore are built into the interpreter itself. _lzma is the C wrapper around the system’s liblzma; the Python-level lzma module imports it. When Python is compiled, its build script checks whether the LZMA headers are present. If they are not, it simply skips that extension and carries on — no error, no warning, just a Python missing one module.

So there is nothing to install from PyPI. There is a package called lzma on PyPI, but it is an old Python 2 backport and installing it will not fix this.

Step 1: confirm the diagnosis#

python -c "import _lzma; print('present')"
python -c "import sysconfig; print(sysconfig.get_config_var('CONFIG_ARGS'))"

If the first fails, check whether other optional modules are missing too — they usually travel together:

for name in ("_lzma", "_bz2", "_sqlite3", "_ssl", "_ctypes", "readline"):
    try:
        __import__(name)
        print(name, "ok")
    except ImportError:
        print(name, "MISSING")

A list of several missing modules tells you Python was built in a minimal environment, and rebuilding will fix all of them at once.

Step 2: install the development library#

Ubuntu and Debian:

sudo apt update
sudo apt install -y liblzma-dev

If you are going to rebuild anyway, install the whole set so you do not have to do this twice:

sudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev \
  libreadline-dev libsqlite3-dev libncursesw5-dev xz-utils tk-dev \
  libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

Fedora, RHEL and CentOS:

sudo dnf install -y xz-devel
sudo dnf groupinstall -y "Development Tools"

Alpine:

apk add xz-dev build-base

macOS with Homebrew:

brew install xz

Step 3: rebuild Python#

Installing the library does nothing on its own — the existing Python was already compiled without it.

With pyenv, which is where this problem appears most often:

pyenv uninstall 3.12.2
pyenv install 3.12.2
pyenv rehash

On macOS, pyenv sometimes needs to be told where Homebrew put the library:

export LDFLAGS="-L$(brew --prefix xz)/lib"
export CPPFLAGS="-I$(brew --prefix xz)/include"
pyenv install 3.12.2

If you compiled Python from source, re-run configure and make:

cd Python-3.12.2
./configure --enable-optimizations
make -j "$(nproc)"
sudo make altinstall

Use altinstall rather than install so you do not replace the system Python your operating system depends on.

Step 4: verify#

python -c "import lzma; print(lzma.__file__)"

import lzma

data = lzma.compress(b"hello world" * 100)
print(len(data), "compressed bytes")
print(lzma.decompress(data)[:11])     # b'hello world'

Avoiding it altogether#

The simplest route is to use a prebuilt Python rather than compiling one:

• Docker: the official python:3.12 images include every optional module. The -alpine variants are smaller and more likely to be missing things.
• System packages: apt install python3 gives you a fully built interpreter.
• Conda: conda-forge builds are complete.
• python.org installers on macOS and Windows are complete.

This error is essentially a pyenv-and-minimal-container problem. If you are not compiling Python yourself, you will rarely meet it.

The related failures#

All have the same shape: install the development package, rebuild Python, verify.

Where to go next#

• Python virtual environments — and why they inherit the base interpreter.
• Fixing ModuleNotFoundError for pandas — the ordinary kind of import error.
• Command line basics — for the build commands above.