no module named bs4: fix ModuleNotFoundError by installing beautifulsoup4, not bs4

Not specified by the original author.

TL;DR

no module named bs4 means nothing named bs4 is installed in the Python that is running your code. The fix is to install the real library under its PyPI name: run python -m pip install beautifulsoup4 (the import name is bs4, the install name is beautifulsoup4), then confirm with python -c "import bs4; print(bs4.version)". If it still fails, you installed into a different interpreter or environment than the one running the script.

ModuleNotFoundError: No module named 'bs4'

Use this when

• The traceback is exactly ModuleNotFoundError: No module named 'bs4', or a log tail shows just no module named bs4
• A fresh machine, container, venv, or CI runner where requirements were never installed
• The same script works on your laptop but fails in Docker or CI

Not for this skill when

• ImportError saying cannot import name 'BeautifulSoup' from 'bs4': something IS installed but it is the stub or a shadow file, a different problem
• FeatureNotFound: bs4 imported fine and a parser is missing instead
• The missing module is a different one (socks, nacl, tokenizers): same shape, different install name; see Related skills

Steps

1. Install beautifulsoup4 into the interpreter you actually run:

python -m pip install beautifulsoup4

Expected: Successfully installed beautifulsoup4 with a 4.x version. Using python -m pip guarantees the package lands in the same interpreter that runs your script.

2. Confirm the import in that same interpreter:

python -c "import bs4; print(bs4.__version__)"

Expected: prints a version like 4.12.3.

3. If it still fails, check for a second Python:

which python
which python3
pip --version

Expected: the paths agree. When pip belongs to a different Python than python, installs go missing; repeating step 1 with python -m pip makes the mismatch disappear.

4. Pin it so it does not come back. Add beautifulsoup4 to requirements.txt, your pyproject dependencies, or your Dockerfile install step.

Expected: a fresh environment built from those files imports bs4 with no error.

Variant phrasings

ModuleNotFoundError: No module named 'bs4'

The full traceback form of this query, with the exception name and quotes. Same missing package, same fix: python -m pip install beautifulsoup4.

no module named 'bs4'

The quoted form, as pasted from a traceback tail or a log. Same fix as above.

works locally, fails in docker or CI

Your local environment has beautifulsoup4 (often pulled in by something else); the image or runner does not. Step 4 is the durable fix: declare the dependency in the file the environment is built from.

Root cause

The distribution name and the import name differ: you pip install beautifulsoup4 but you import bs4. People who guess pip install bs4 get the 0.0.1 placeholder package instead, which converts this error into the nastier cannot import name 'BeautifulSoup' one. The other classic cause is installing into one Python while running another, which is why python -m pip is the reliable spelling.

Edge cases

• Do NOT pip install bs4. That installs the placeholder and makes the next error harder.
• Conda users: conda install beautifulsoup4 from defaults or conda-forge works the same.
• In Docker, make sure the pip install layer actually ran; a cached layer from before beautifulsoup4 was added to requirements silently skips it.
• A local file named bs4.py in your project folder shadows the real package; rename it if the import resolves to your file.

Tool compatibility

All beautifulsoup4 4.x on Python 3. The PyPI name has been beautifulsoup4 since the beginning; the top-level import has always been bs4. pip, conda, Docker, and CI runners all follow the same rule.

Related skills

• ModuleNotFoundError: No module named 'socks' (same import-name vs install-name trap, in requests): https://vectle.com/skills/sklFlB19WyD4leM499zch4jQ
• atlassian-python-api fails on import with ModuleNotFoundError: No module named 'bs4': https://vectle.com/skills/skl_M4NYvQlI7UbHhNAS16Vc1w

Provenance

Built from a documented GitHub issue where this error was fixed by installing beautifulsoup4, linked in the evidence.

In gh:jarrettr/stretch#36 a user hit ModuleNotFoundError: No module named 'bs4' trying to run the stretch project, and the fix was installing the project's dependencies including beautifulsoup4 (the PyPI name) rather than anything named bs4. This name mismatch is the single most common cause of the report. Source: https://github.com/jarrettr/stretch/issues/36