PyTorch "undefined symbol" torchvision/torch ABI mismatch in CI

By Daniel Zoghalchali·Latchkey

Importing torchvision or torchaudio fails because its compiled C++ extension references a symbol that the installed torch build does not export. The companion package was built against a different torch version than the one present.

What this error means

Importing torchvision raises "ImportError: ... undefined symbol: _ZN...", a long mangled C++ name, pointing at the torchvision shared object.

ImportError: /opt/venv/lib/python3.12/site-packages/torchvision/image.so:
undefined symbol: _ZN3c1017RegisterOperatorsD1Ev

Diagnose it: is it the build backend or a missing system library?

Python packaging failures in CI split into build-backend configuration problems and missing system headers. The traceback usually points at the backend even when the real cause is an absent -dev package.

python -m pip install --upgrade pip build
python -m build --wheel 2>&1 | tail -40

# a compiler error naming a .h file is a system dependency, not a Python one
#   e.g. "Python.h: No such file" -> python3-dev
#        "openssl/ssl.h"          -> libssl-dev

Common causes

torch and torchvision versions are mismatched

torchvision is pinned to an exact torch version. Installing or upgrading one without the other leaves the compiled extension linked against symbols the installed torch no longer exports.

Mixed CPU and CUDA wheels

A CPU torch with a CUDA torchvision (or different cu suffixes) produces incompatible binaries and undefined symbols at import.

How to fix it

Install torch and torchvision as a matched set

1. Pick the torchvision version that pairs with your torch version from the compatibility matrix.
2. Install both from the same index and CUDA suffix in one command.
3. Re-import torchvision to confirm the symbol resolves.

pip install --index-url https://download.pytorch.org/whl/cu121 \
  torch==2.3.1 torchvision==0.18.1

Reinstall both cleanly to avoid a half upgrade

Force reinstall as a pair so no stale extension from a previous version remains.

pip install --force-reinstall --no-deps \
  torch==2.3.1 torchvision==0.18.1

How to prevent it

• Always upgrade torch and torchvision/torchaudio together.
• Use the same index URL and cu suffix for every torch package.
• Pin the matched trio in a lockfile so CI installs them as a set.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation