ImportError: cannot import name 'Document' from 'readability'

You installed the wrong package. PyPI has TWO projects in this namespace: readability (an unrelated stub) and readability-lxml (the article extractor, imported as readability). Run pip uninstall readability -y then pip install readability-lxml, and from readability import Document works.

The error

ImportError: cannot import name 'Document' from 'readability'

Fix it

1. Remove the wrong package

python -m pip uninstall readability -y

Expected: the unrelated readability project is gone.

1. Install the real one

python -m pip install readability-lxml

Expected: Successfully installed readability-lxml-....

1. Confirm

python -c "from readability import Document; print('ok')"

Expected: prints ok.

When this applies

• from readability import Document raises ImportError naming Document
• pip show readability shows a version but no Document class exists
• you followed a guide that said pip install readability

When it does NOT apply

• No module named 'readability' means nothing is installed at all
• from partially initialized module 'readability' is the circular-import variant (your own readability.py)

Compatibility

readability-lxml 0.8.x. The unrelated readability package on PyPI is the trap; it has no Document class.

Why it happens

A name collision on PyPI: readability (a different, tiny project) vs readability-lxml (the article-extraction library everyone means, which chose readability as its import name). Installing the bare name gives you a package with no Document in it, so the class import fails while the module import succeeds.

Edge cases

• If both are installed, the wrong one wins nondeterministically depending on install order. Uninstalling readability first (step 1) is essential, not optional.
• Old tutorials genuinely say pip install readability because the collision did not exist yet. Mentally translate every such instruction to readability-lxml.