docs/errors/setuptools_backends_legacy.md

BackendUnavailable — setuptools.backends.legacy

Date: 2026-04-12
Project: Neural Machine Translation
Environment: Windows 11, Python 3.12.9

---

Error message

pip._vendor.pyproject_hooks._impl.BackendUnavailable:
Cannot import 'setuptools.backends.legacy'

Context

Running pip install -e . after creating pyproject.toml with build-backend = "setuptools.backends.legacy:build".

Why it happened

The setuptools.backends.legacy module only exists in newer versions of setuptools. The installed version was too old to support it.

What fixed it

Step 1 — Updated pyproject.toml to use the stable backend:

[build-system]
requires = ["setuptools>=64"]
build-backend = "setuptools.build_meta"

Step 2 — Upgraded setuptools and reinstalled:

pip install --upgrade setuptools
pip install -e .

Lesson learned

Always use setuptools.build_meta as the build backend — it's the stable, well-supported option that works across all setuptools versions >= 64. Never use setuptools.backends.legacy — it's version-specific and unreliable.