Skip to main content

How to Solve "ModuleNotFoundError: No module named 'bs4'" in Python

The error ModuleNotFoundError: No module named 'bs4' means that your Python environment can not find the bs4 module, which is part of the Beautiful Soup 4 library. Beautiful Soup is a popular library for parsing HTML and XML.

This guide explains how to fix this error by correctly installing beautifulsoup4 and addresses common installation pitfalls.

Understanding the Error: bs4 vs. beautifulsoup4​

It's crucial to understand the distinction:

  • beautifulsoup4: This is the package name you use with pip to install Beautiful Soup.
  • bs4: This is the module name you use to import Beautiful Soup in your Python code.

You install beautifulsoup4, but you import bs4.

Installing beautifulsoup4 with pip​

The standard way to install Beautiful Soup is using pip, Python's package installer.

Basic Installation​

Open your terminal (or command prompt on Windows) and run:

pip install beautifulsoup4

If you have multiple Python versions installed, or if your pip command is associated with Python 2, you might need to use pip3:

pip3 install beautifulsoup4

Using python -m pip (When pip Isn't in Your PATH)​

If the pip command doesn't work (e.g., you get a "command not found" error), it might not be in your system's PATH. Use this command instead:

python -m pip install beautifulsoup4  # Use with your system's default Python
python3 -m pip install beautifulsoup4 # Use with your system's Python 3

This explicitly runs pip using the Python interpreter.

Windows-Specific Considerations (py launcher)​

On Windows, the py launcher is often the best way to select the correct Python version:

py -m pip install beautifulsoup4
  • The py command uses the latest version of Python.

Permissions Issues (sudo or --user)​

On Linux or macOS, you might need sudo to install packages globally:

sudo pip3 install beautifulsoup4  # Use sudo for system-wide installation
  • Using the sudo will install the package globally, in the system.

Alternatively (and generally preferred), install into your user's site-packages directory without needing sudo:

pip install beautifulsoup4 --user  # Install for the current user only
  • Using --user will install the package for the current user.

Always use virtual environments for Python projects. They isolate your project's dependencies, preventing conflicts and making your projects reproducible.

Creating a Virtual Environment​

python3 -m venv venv  # Create a virtual environment named "venv"
# OR:  python -m venv venv
# OR:  py -m venv venv  (Windows)

This creates a directory named venv (you can use any name) containing a self-contained Python environment.

Activating the Environment​

  • macOS / Linux:

    source venv/bin/activate

  • Windows (Command Prompt):

    venv\Scripts\activate.bat

  • Windows (PowerShell):

    venv\Scripts\Activate.ps1

    If activating on Windows (PowerShell) does not work, you may have to change the execution policy, by running the following command and confirming with y:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

After activation, your command prompt will usually show the environment name in parentheses (e.g., (venv)). Now, any pip install commands will install packages into this environment only.

Installing beautifulsoup4 Inside the Environment​

With your virtual environment activated, install Beautiful Soup:

pip install beautifulsoup4  # Installs into the active environment

Troubleshooting​

If you've installed beautifulsoup4 but still get the ModuleNotFoundError, consider these:

  • IDE Configuration (VS Code, PyCharm): Your IDE might be using a different Python interpreter than the one you used to install the package.
    • VS Code: Press Ctrl+Shift+P (or Cmd+Shift+P on macOS), type "Python: Select Interpreter", and choose the correct interpreter (the one associated with your virtual environment, if applicable).
    • PyCharm: Go to File > Settings > Project > Python Interpreter (or PyCharm > Preferences > Project > Python Interpreter on macOS) and select the correct interpreter.
  • Conflicting Installations/Multiple Python Versions: If you have multiple Python versions installed without using virtual environments, you might have installed beautifulsoup4 for the wrong version. Always use virtual environments to avoid this.
  • Incorrect Filenames or Variable Names (bs4.py): Never name your own Python files the same as a module you're trying to import (e.g., don't name a file bs4.py). This will cause a conflict. Similarly, don't create a variable named bs4 before importing the module.
  • Restarting Your IDE/Kernel: Sometimes, especially in interactive environments like Jupyter notebooks or after installing a new package, you need to restart the Python kernel or the entire IDE for changes to take effect.

Using Beautiful Soup (Example)​

Once installed correctly, you can import and use Beautiful Soup:

from bs4 import BeautifulSoup

html_doc = """
<html><head><title>The Dormouse's story</title></head>
<body>
<p class="title"><b>The Dormouse's story</b></p>

<p class="story">Once upon a time there were three little sisters; and their names were
<a href="http://example.com/elsie" class="sister" id="link1">Elsie</a>,
<a href="http://example.com/lacie" class="sister" id="link2">Lacie</a> and
<a href="http://example.com/tillie" class="sister" id="link3">Tillie</a>;
and they lived at the bottom of a well.</p>

<p class="story">...</p>
"""

soup = BeautifulSoup(html_doc, 'html.parser')
print(soup.prettify())

Installing the parser lxml​

You will also need a parser for BeautifulSoup to work. One popular option is lxml.

Install it by running the command:

pip install lxml

Table of Contents