How to Resolve "ModuleNotFoundError: No module named urllib2" Error in Python

When migrating older Python 2 code or running legacy scripts in a Python 3 environment, you will likely encounter the ModuleNotFoundError: No module named 'urllib2'. This error occurs because a significant reorganization of Python's standard library for handling URLs took place between Python 2 and Python 3. The urllib2 module, which was a staple for web requests in Python 2, does not exist in Python 3.

This guide will explain this change, show you how to fix the error by updating your code to use the modern urllib.request module, and provide methods for maintaining compatibility or automating the migration process.

Understanding the Error: The Renaming of urllib2 in Python 3

The ModuleNotFoundError is a direct consequence of the Python 2 to Python 3 transition. In Python 2, URL handling functionality was split across several modules, including urllib, urllib2, and urlparse. This was often confusing for developers.

In Python 3, these modules were consolidated and refactored into a single urllib package with several submodules:

• urllib2 was largely replaced by urllib.request and urllib.error.
• urllib was largely replaced by urllib.request, urllib.parse, and urllib.error.
• urlparse was moved to urllib.parse.

Therefore, when Python 3 encounters import urllib2, it cannot find the module and raises the ModuleNotFoundError.

Reproducing the ModuleNotFoundError

The following code, which was valid in Python 2, will reliably trigger the error when executed with a Python 3 interpreter.

Example of the code causing the error:

from urllib2 import urlopen

try:
    response = urlopen("https://www.python.org")
    print("Request successful.")
except NameError as e:
    print(f"urlopen is not defined because of the import error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

Output when run with python3:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ModuleNotFoundError: No module named 'urllib2'

Solution 1: Update the Import to urllib.request (Recommended)

The standard and most direct way to fix this error for modern Python 3 code is to change the import statement to use the urllib.request submodule.

Solution:

from urllib.request import urlopen

response = urlopen("https://www.python.org")
print(f"Request successful, status code: {response.getcode()}")
print(f"First 100 bytes of response: {response.read(100)}")

Output:

Request successful, status code: 200
First 100 bytes of response: b'<!doctype html>\n<!--[if lt IE 7]><html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9"><![endif]-->\n<!--[if IE'

Solution 2: Use a try-except Block for Python 2 & 3 Compatibility

If you are writing a library or application that needs to support both Python 2 and Python 3, you can use a try-except block to handle the different import paths gracefully.

The Compatibility Solution:

try:
    from urllib.request import urlopen
except ImportError:
    from urllib2 import urlopen

response = urlopen("https://www.python.org")
print(f"Request successful, status code: {response.getcode()}")

Output (in either Python 2 or 3):

Request successful, status code: 200

Solution 3: Use the 2to3 Tool for Automatic Code Migration

If you are migrating a larger Python 2 codebase, manually changing every import statement can be tedious. Python provides a command-line tool called 2to3 that automatically converts Python 2 code to Python 3 syntax, including fixing urllib2 imports.

The Automatic Conversion Solution: Suppose you have a file named script.py with Python 2 code.

2to3 script.py

2to3 -w script.py

Running this tool will automatically transform lines like from urllib2 import urlopen into from urllib.request import urlopen.

Conclusion

The ModuleNotFoundError: No module named 'urllib2' is a clear indicator that you are running Python 2 code in a Python 3 environment. To resolve it:

1. For modern Python 3 code, the best practice is to manually update your imports from urllib2 to the appropriate urllib submodule, typically urllib.request.
2. For code that must support both versions, use a try-except ImportError block to create a compatibility layer.
3. For migrating entire projects, the 2to3 command-line tool can automate the conversion process, saving significant time and effort.

By understanding this fundamental change between Python 2 and 3, you can easily update your code to work correctly in modern Python environments.