Skip to main content

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

The ModuleNotFoundError: No module named 'urllib3' error in Python indicates that the urllib3 library is not installed in your current Python environment. urllib3 is a powerful, user-friendly HTTP client for Python. It's often a dependency of other libraries, such as requests.

This guide provides a step-by-step approach to resolving this error, including installation, troubleshooting, and environment-specific instructions.

Understanding the Error​

The ModuleNotFoundError means that when your Python code tries to import urllib3, the interpreter can't find the package. This usually means it's not installed, or it's installed in a different environment than the one you're currently using.

Installation with pip​

The standard way to install urllib3 is with pip:

pip install urllib3

# OR, for Python 3 (might be pip3, pip3.10, etc. on your system)
pip3 install urllib3

# OR, if pip is not in your PATH:
python -m pip install urllib3
python3 -m pip install urllib3

# OR, for Windows 'py' launcher:
py -m pip install urllib3

Choose the command that works best for your system. The python -m pip (or equivalent) form is generally the most reliable because it uses the specific Python interpreter you intend.

Troubleshooting ModuleNotFoundError​

If you still get the error after installation, work through these steps:

Virtual Environments (Essential!)​

Always use virtual environments for Python projects to isolate dependencies.

  1. Create (if needed):

    python3 -m venv venv  # Recommended
    # OR (if the above fails)
    python -m venv venv
    # OR (Windows)
    py -m venv venv

  2. Activate:

    • Linux/macOS (bash/zsh): source venv/bin/activate
    • Windows (Command Prompt): venv\Scripts\activate.bat
    • Windows (PowerShell): venv\Scripts\Activate.ps1 If PowerShell throws a security error, you may need to run the command: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

  3. Install inside the activated environment: pip install urllib3

Checking Your Python Version​

If you have multiple versions installed, be explicit.

python --version
python3 --version

Use pip or pip3 that matches the python version you are using to run your code.

Verifying Installation​

Confirm that urllib3 is installed in the correct environment:

pip show urllib3
# OR
python -m pip show urllib3

This displays package information, including the installation location. If it says "Package not found," it's not installed in the current environment. Check the Location: field; it should be within your virtual environment (if you're using one).

IDE Configuration (VS Code, PyCharm)​

Your IDE must be configured to use the correct Python interpreter (the one with urllib3 installed).

  • VS Code: Use the Python: Select Interpreter command from the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
  • PyCharm: Go to File > Settings > Project > Python Interpreter (or PyCharm > Preferences > Project > Python Interpreter on macOS).

Naming Conflicts (Shadowing)​

Make absolutely sure you don't have a file or directory named urllib3.py (or just urllib3) in your project or anywhere on your PYTHONPATH. This will shadow the installed urllib3 package. Rename your file if necessary.

Reinstall and Upgrade​

If you suspect a corrupted installation, try the following steps:

pip uninstall urllib3
pip install urllib3
pip install urllib3 --upgrade # upgrade if needed

requests and urllib3​

If you're using the popular requests library, it already includes urllib3 as a dependency. Upgrading requests can sometimes resolve issues:

pip install requests --upgrade
# OR
python -m pip install requests --upgrade

Installation in Specific Environments​

Anaconda​

conda install -c conda-forge urllib3

Jupyter Notebook​

!pip install urllib3

Basic Example​

import urllib3

http = urllib3.PoolManager()
r = http.request('GET', 'http://httpbin.org/robots.txt')
print(r.status) # Output: 200
print(r.data)   # Output: b"User-agent: *\nDisallow: /deny\n"

Conclusion​

The ModuleNotFoundError: No module named 'urllib3' error is usually a simple installation or environment problem.

By carefully following the installation instructions, using virtual environments, and checking for naming conflicts, you can quickly resolve this error and start using urllib3 for your HTTP requests.

Remember to check your IDE's interpreter settings if you're using an IDE.

Table of Contents