ImportError: cannot import name BeautifulSoup

MechanicalSoup itself is fine; its import chain runs from bs4 import BeautifulSoup, and the bs4 on this system is the dummy bs4 0.0.1 stub from PyPI (installed by pip install bs4), which contains no code. Run pip uninstall bs4 -y then pip install beautifulsoup4, and import mechanicalsoup works. On modern Python the same trap prints the newer quoted message.

The error

ImportError: cannot import name BeautifulSoup

Fix it

1. Check for the stub package

python -m pip show bs4

Expected: if it reports version 0.0.1, that is the placeholder package. A real beautifulsoup4 shows as beautifulsoup4 with version 4.x.

1. Remove the stub, install the real library

python -m pip uninstall bs4 -y
python -m pip install beautifulsoup4

Expected: the stub is gone and beautifulsoup4 4.x is installed.

1. Confirm the whole chain

python -c "import mechanicalsoup; print('ok')"

Expected: prints ok. The from bs4 import BeautifulSoup inside mechanicalsoup now finds the real class.

When this applies

• import mechanicalsoup fails with ImportError: cannot import name BeautifulSoup (old-style, no quotes)
• the traceback shows mechanicalsoup's __init__ -> browser.py -> form.py -> from bs4 import BeautifulSoup
• pip show bs4 reports version 0.0.1

When it does NOT apply

• ModuleNotFoundError: No module named 'bs4' means nothing named bs4 exists at all
• the quoted modern form (cannot import name 'BeautifulSoup' from 'bs4') is the same trap on newer Python
• No module named 'mechanicalsoup' means MechanicalSoup itself is missing

Compatibility

Seen on Python 2 / early Python 3, which printed the unquoted message format. The underlying stub-package trap exists on every Python version.

Variant phrasings

ImportError: cannot import name 'BeautifulSoup' from 'bs4'

The same stub-package trap as printed by Python 3.6+. Same fix: uninstall the bs4 stub, install beautifulsoup4.

Why it happens

PyPI hosts a placeholder package literally named bs4 (version 0.0.1) whose only content is a note saying to install beautifulsoup4 instead. pip install bs4 installs that empty shell. MechanicalSoup imports from bs4 import BeautifulSoup during its own import, so the empty shell breaks import mechanicalsoup even though MechanicalSoup itself is correctly installed. Old Pythons printed the message without quotes or the from-clause, which is the exact string here.

Edge cases

• Kodi-style addon environments vendor old library copies. If uninstalling the stub is not possible there, make sure beautifulsoup4 is installed in the same addon lib folder and takes precedence.
• After removing the stub, clear __pycache__ in the project. A cached empty bs4 module can linger.