Skip to main content

How to Resolve Python "NameError: name 'reload' is not defined"

If you're transitioning from Python 2 or working in an interactive Python 3 session, you might encounter the NameError: name 'reload' is not defined. This error occurs because the reload() function, which was a built-in function in Python 2, was moved to the standard library's importlib module in Python 3.

This guide explains why this NameError happens in Python 3 and shows the correct ways to import and use the reload functionality.

Understanding the Error: Python 2 vs. Python 3​

In Python 2, reload() was readily available as a built-in function to re-execute the code of an already imported module. However, as part of Python 3's standard library cleanup and organization, reload() was relocated to the importlib module, which deals with the implementation of the import statement. Therefore, directly calling reload(module_name) in Python 3 without importing it first results in a NameError.

Cause: reload is Not Built-in in Python 3​

The NameError simply means the name reload is not recognized in the current scope because it hasn't been defined or imported.

import math # Example module to reload

try:
    # ⛔️ NameError: name 'reload' is not defined
    # Calling reload directly without importing it from importlib
    reloaded_math = reload(math)
    print(reloaded_math)
except NameError as e:
    print(e)

Solution 1: Import importlib and Use importlib.reload()​

The first way to fix this is to import the entire importlib module and then call the reload function using the module name as a prefix.

import math         # The module we want to reload
import importlib    # Import the importlib module

print(f"Original math module: {math}")

# Call reload using the module prefix
reloaded_math = importlib.reload(math)

print(f"Reloaded math module: {reloaded_math}")

Output (will vary slightly based on environment):

Original math module: <module 'math' (built-in)>
Reloaded math module: <module 'math' (built-in)>

This approach works correctly but requires typing importlib. each time you use reload.

A more common and often preferred approach is to import only the reload function directly from the importlib module. This adds the reload name directly to your current scope.

import math                   # The module we want to reload
from importlib import reload  # Import reload specifically

print(f"Original math module: {math}")

# Call reload directly by its name
reloaded_math = reload(math)

print(f"Reloaded math module: {reloaded_math}")

Output (will vary slightly based on environment):

Original math module: <module 'math' (built-in)>
Reloaded math module: <module 'math' (built-in)>

This method is generally recommended because:

  • It's slightly less verbose (reload(...) vs importlib.reload(...)).
  • It makes it clear at the top of the file that the reload function is being used.

How reload() Works​

The importlib.reload(module) function attempts to re-parse and re-execute the code of an already imported module object. Key points:

  • Argument: It takes a module object (like math in the examples, which was previously imported) as its argument, not a module name string.
  • Mechanism: It re-reads the module's source file (if available) and re-executes its top-level code within the existing module namespace. Existing objects defined in the module are updated in place where possible.
  • Return Value: It returns the (reloaded) module object. It's often good practice to capture this return value, although reloading modifies the existing module object directly as well.

When to Use reload() (Use Cases & Cautions)​

reload() is primarily useful in interactive development sessions (like the Python REPL or Jupyter notebooks) where you might:

  • Modify the source code of a module you're working on in an external editor.
  • Want to test those changes immediately without restarting the entire Python interpreter or kernel.

Cautions:

  • Not for Production: reload() is generally not recommended for use in production applications. Reloading modules can have complex and unpredictable side effects, especially with dependencies, class instances, or background threads. Restarting the application is usually safer for applying changes in production.
  • Side Effects: Reloading updates the module's namespace, but existing instances of classes defined in the module are not automatically updated to use the new method definitions. References to old objects might persist.
  • Dependencies: It does not recursively reload modules imported by the module you are reloading.

Use reload() judiciously during development for quick iteration, but prefer restarting your application for applying changes in more stable environments.

Conclusion​

The NameError: name 'reload' is not defined in Python 3 occurs because reload is no longer a built-in function. It now resides in the importlib module.

To fix the error, you must import it before use:

  1. import importlib and call importlib.reload(module_object).
  2. (Recommended) from importlib import reload and call reload(module_object).

Remember that reload() is mainly intended for interactive development and should generally be avoided in production code due to potential side effects.

Table of Contents