Last modified: Apr 21, 2026 By Alexander Williams
Fix ModuleNotFoundError: No module named 'bs4'
If you are building a web scraper in Python and you run into ModuleNotFoundError: No module named 'bs4', do not panic. This is one of the most common errors developers face when working with HTML parsing and web scraping projects.
This error means Python cannot find the bs4 module in your current environment. It is a simple installation issue that can be fixed in just a few minutes. In this article, you will learn exactly why this error happens and how to solve it across every major Python environment.
What Is the bs4 Module?
bs4 is the import name for BeautifulSoup4, one of the most widely used Python libraries for parsing HTML and XML documents. It is a core tool in web scraping workflows.
With BeautifulSoup4, you can easily navigate and search through the structure of a web page. The main class you use is BeautifulSoup(), which takes raw HTML as input and turns it into a parsed, searchable tree structure.
BeautifulSoup4 is not part of the Python standard library. This means Python does not include it by default. You must install it separately before you can import it in your code.
It is important to know the difference between the import name and the package name:
Import name: bs4 — this is what you use in your Python code with import bs4
Package name: beautifulsoup4 — this is what you use when installing with pip
Confusing these two names is one of the most common causes of this error.
What Causes This Error?
Here is what the full error looks like when it appears in your terminal:
from bs4 import BeautifulSoup
Traceback (most recent call last):
File "scraper.py", line 1, in <module>
from bs4 import BeautifulSoup
ModuleNotFoundError: No module named 'bs4'
The most common causes of this error are:
1. beautifulsoup4 is not installed — You have never installed the package in your current environment.
2. Wrong package name used during installation — Many beginners try to install it as bs4 instead of beautifulsoup4, which installs a different or outdated package.
3. Wrong Python environment — You installed beautifulsoup4 in a different Python version or environment than the one running your script.
4. Virtual environment not activated — The package was installed globally, but your script is running inside a virtual environment where it is not available.
5. Corrupted or incomplete installation — The installation was interrupted and left the package in a broken state.
Fix 1: Install beautifulsoup4 Using pip
The most straightforward fix is to install beautifulsoup4 using pip. Open your terminal or command prompt and run:
pip install beautifulsoup4
If you are using Python 3 and have multiple Python versions installed, use:
pip3 install beautifulsoup4
After installation, confirm it was installed correctly:
pip show beautifulsoup4
Name: beautifulsoup4
Version: 4.12.2
Summary: Screen-scraping library
Home-page: https://www.crummy.com/software/BeautifulSoup/bs4/
Author: Leonard Richardson
Now test it in a simple Python script:
from bs4 import BeautifulSoup
# Simple HTML string to parse
html = "<html><body><h1>Hello, World!</h1></body></html>"
# Parse the HTML using BeautifulSoup
soup = BeautifulSoup(html, "html.parser")
# Extract the h1 tag text
print(soup.h1.text)
Hello, World!
If you see this output, the error is resolved and BeautifulSoup4 is working correctly.
Fix 2: Avoid the Wrong Package Name
This is one of the most important things to remember. Many developers try to install the package using its import name and end up with a completely different or outdated package.
# WRONG - do not install this
pip install bs4
# CORRECT - always use this
pip install beautifulsoup4
The package named bs4 on PyPI is an old, unmaintained stub package. It is not the real BeautifulSoup library. Installing it will not fix the error. Always use beautifulsoup4 as the installation name.
Fix 3: Use the Correct Python Interpreter
If you have multiple Python versions installed, it is easy to accidentally install a package in the wrong one. The safest way to install beautifulsoup4 is to use the -m pip approach:
python -m pip install beautifulsoup4
This guarantees that the package is installed into the same Python interpreter you are using to run your script. You can also target a specific Python version:
python3.11 -m pip install beautifulsoup4
Check which Python is currently active before installing:
python --version
which python
Python 3.11.5
/usr/local/bin/python
Always confirm that both your script and your pip installation are pointing to the same Python environment.
Fix 4: Activate Your Virtual Environment
If you are using a virtual environment, you must activate it before installing any packages. This is an extremely common mistake among beginners.
To create and activate a virtual environment on Linux or macOS:
# Create a virtual environment
python -m venv myenv
# Activate the virtual environment
source myenv/bin/activate
# Install beautifulsoup4 inside the environment
pip install beautifulsoup4
To do the same on Windows:
# Create a virtual environment
python -m venv myenv
# Activate on Windows
myenv\Scripts\activate
# Install beautifulsoup4
pip install beautifulsoup4
Once activated, your terminal prompt will show the name of the virtual environment in parentheses. Always verify this prefix is visible before running pip install commands.
Fix 5: Install bs4 in Anaconda
If you are using the Anaconda distribution, use the conda package manager for a cleaner installation experience:
conda install -c anaconda beautifulsoup4
Or install from the conda-forge channel:
conda install -c conda-forge beautifulsoup4
Always activate the correct conda environment first:
# Activate your conda environment
conda activate myenv
# Then install
conda install -c anaconda beautifulsoup4
If you prefer using pip inside a conda environment, that also works fine:
pip install beautifulsoup4
Fix 6: Install bs4 in Jupyter Notebook
If you are using Jupyter Notebook, installing from your system terminal may not affect the active kernel. Run the installation directly inside a notebook cell to avoid this problem:
import sys
# Install beautifulsoup4 in the current Jupyter kernel
!{sys.executable} -m pip install beautifulsoup4
Using sys.executable is essential here. It ensures pip installs into the exact Python kernel that Jupyter is currently using.
After the installation finishes, go to Kernel → Restart to reload the environment. Then try your import again:
from bs4 import BeautifulSoup
# Test inside Jupyter Notebook
html = "<p>BeautifulSoup is now working in Jupyter!</p>"
soup = BeautifulSoup(html, "html.parser")
print(soup.p.text)
BeautifulSoup is now working in Jupyter!
Fix 7: Install bs4 in a Docker Container
If your Python application runs inside a Docker container, you need to include beautifulsoup4 in your container build process.
Add it to your requirements.txt file:
beautifulsoup4
requests
lxml
Or install it directly inside your Dockerfile:
RUN pip install beautifulsoup4
Then rebuild the Docker image:
docker build -t myapp .
Fix 8: Reinstall to Fix a Corrupt Installation
If beautifulsoup4 appears to be installed but the error still occurs, the installation may be corrupted. Do a clean reinstall:
# Remove the existing installation
pip uninstall beautifulsoup4
# Reinstall fresh
pip install beautifulsoup4
To upgrade to the latest version at the same time:
pip install --upgrade beautifulsoup4
Install a Parser for BeautifulSoup4
BeautifulSoup4 requires a parser to process HTML. Python includes the built-in html.parser, which works fine for most cases. However, for better performance and more robust parsing, it is recommended to install lxml or html5lib:
# Install the fast lxml parser
pip install lxml
# Or install html5lib for better HTML5 support
pip install html5lib
Here is how to use each parser with BeautifulSoup:
from bs4 import BeautifulSoup
html = """
<html>
<body>
<h1>Web Scraping with Python</h1>
<p class="intro">BeautifulSoup makes HTML parsing easy.</p>
</body>
</html>
"""
# Using the built-in html.parser (no extra install needed)
soup1 = BeautifulSoup(html, "html.parser")
# Using lxml (faster, recommended for large pages)
soup2 = BeautifulSoup(html, "lxml")
# Using html5lib (best HTML5 compatibility)
soup3 = BeautifulSoup(html, "html5lib")
print(soup1.h1.text)
print(soup1.find("p", class_="intro").text)
Web Scraping with Python
BeautifulSoup makes HTML parsing easy.
Fix the Error in VS Code or PyCharm
If you are working in VS Code or PyCharm, the error can appear even after a successful installation. This happens when the IDE is configured to use a different Python interpreter than the one where you installed the package.
In VS Code, press Ctrl + Shift + P (or Cmd + Shift + P on Mac), search for Python: Select Interpreter, and choose the correct environment where beautifulsoup4 is installed.
In PyCharm, go to File → Settings → Project → Python Interpreter. From there, you can switch to the correct interpreter or install packages directly using the + button in the interface.
Related Errors You May Encounter
If you are working on web scraping or data projects, you may also run into similar errors with other libraries. For instance, ModuleNotFoundError: No module named 'IPython' is common in interactive Python workflows and follows the same root cause — a missing package in the active environment.
Similarly, ModuleNotFoundError: No module named 'serial' is frequently encountered in hardware and IoT projects. In all these cases, the fix is the same: identify your active Python environment and install the missing package into it.
Verify Your Full Environment
Before installing any package, it is a good habit to verify that Python and pip are pointing to the same environment. This prevents the most common installation mistakes.
# Check active Python path
which python
# Check active pip path
which pip
# Verify beautifulsoup4 is installed
pip list | grep beautifulsoup4
/home/user/myenv/bin/python
/home/user/myenv/bin/pip
beautifulsoup4 4.12.2
When Python and pip both point to the same environment path, all package installations will work reliably.
Conclusion
The ModuleNotFoundError: No module named 'bs4' error is very common but always easy to resolve. In the vast majority of cases, the fix is simply running pip install beautifulsoup4 in your terminal.
The most important things to remember are: always use beautifulsoup4 as the package name during installation, never bs4. Always make sure you are installing into the correct Python environment. And always activate your virtual environment before running any pip commands.
Once BeautifulSoup4 is properly installed, you have access to one of the most powerful and easy-to-use HTML parsing libraries in the Python ecosystem. Whether you are scraping product prices, extracting news headlines, or building a data pipeline from web sources, BeautifulSoup4 gives you the tools to get the job done efficiently.