Reload Imported Modules in Python

When you edit a Python module during an interactive development session, the changes do not take effect because Python caches every imported module in memory. To reload imported modules in Python, you can use the importlib.reload function, which forces Python to re-execute a module's source file and update the cached module object without restarting the interpreter.

Module reloading is a development tool, not a deployment strategy. It exists to make the edit-test loop faster during interactive programming, and it should not appear in production code that runs unattended. Understanding what reload does, what it cannot do, and how its limitations can surprise you is important for using it effectively and for knowing when to reach for a different approach entirely.

How reloading works

The reload function lives in the importlib module, which is part of the standard library. You pass it an already-imported module object, and it re-executes the module's source file, updating the module object's namespace with any new or changed definitions. The module object remains the same Python object in memory, which means any other module that imported this module still holds a reference to the same object and will see the updated names on the next access.

python

import importlib
import mymodule
 
importlib.reload(mymodule)

The reload process re-executes all top-level code in the module, including function and class definitions, variable assignments, and any import statements inside the module. This means that if you changed a function body, added a new function, or modified a class definition, those changes appear in the reloaded module. It also means that any side effects in the module's top-level code, such as print statements, file creation, or network calls, will happen again on every reload, which is another reason to keep top-level code minimal and free of side effects.

Reloading does not re-import the modules that your module depends on. If your module imports a helper module and you changed both files, reloading only your module will pick up your changes but not the changes to the helper. You must reload the helper first, then reload your module, for all changes to take effect. This dependency ordering is manual and error-prone, which is one reason that automatic reload tools and full interpreter restarts are preferred for complex projects.

What reloading cannot update

The most important limitation of reloading is that it does not retroactively update objects that were created before the reload. If you imported a class from a module, created an instance of that class, and then reloaded the module after changing the class definition, the existing instance still references the old class. Calling methods on it will execute the old code. Only new instances created after the reload will use the updated class definition.

This limitation extends to function references stored in variables, modules imported into other namespaces, and any object that holds a reference to something from the old version of the module. Reloading updates the module's namespace, but it cannot reach into every variable in every other module that might be holding a stale reference. This is why reloading works well for simple utility modules that are called directly by name after each edit, but breaks down for complex object graphs where old references linger in unexpected places.

The following example illustrates the problem. After reloading a module that defines a class, an instance created before the reload still uses the old class definition. Only a new instance created after reloading reflects the changes:

python

import mymodule
 
old_obj = mymodule.MyClass()
importlib.reload(mymodule)
new_obj = mymodule.MyClass()
 
print(type(old_obj) is type(new_obj))

This prints False because the old object's class is the version from before the reload, while the new object's class is the reloaded version. Python treats them as different classes even though they have the same name and came from the same module file.

When to use reloading

Reloading is appropriate in interactive Python sessions, including the standard REPL, IPython, and Jupyter notebooks, where you are editing a module file in one window and testing it in another. Instead of closing the interpreter, reopening it, re-importing all your modules, and recreating your test data, you reload the one module you changed and continue working. This shortens the feedback loop from minutes to seconds and makes exploratory programming more fluid.

Reloading is also useful when building and debugging packages with subpackages where you need to test changes to a deeply nested module without restarting the entire application. By reloading the specific module you are working on, you can iterate on its implementation while the rest of the application remains running with its existing state.

Reloading is not appropriate in production code, in scripts that run unattended, or in any context where reliability matters more than development speed. Production deployments should restart the Python process when code changes, which guarantees a clean state and eliminates the entire category of bugs caused by stale references to old module versions. If you find yourself wanting to reload modules in production, the real solution is to restructure your code so that the changing behavior can be configured or swapped at runtime through a plugin system or a configuration file, rather than through module reloading.

Alternatives to manual reloading

IPython and Jupyter provide an autoreload extension that monitors module files for changes and automatically reloads them before executing each cell. This eliminates the need to call reload manually and ensures that you are always working with the latest version of your code. Enable it with a magic command at the start of your session, and it handles the reload ordering and dependency tracking that manual reloading requires you to manage yourself.

For larger projects where even autoreload becomes unwieldy, file-watching tools can restart your Python process whenever a source file changes. This approach trades the speed of in-process reloading for the reliability of a clean restart, and it is the standard workflow for web development frameworks that include development servers with hot-reload capabilities. The application restarts in under a second on modern hardware, which is fast enough that the reliability gain outweighs the slight delay.

Understanding how modules are cached and reloaded also deepens your understanding of the broader import system. When you learned about importing modules in Python, the cache was described as the mechanism that prevents redundant work. Reloading is the escape hatch that lets you override that cache when you intentionally want redundant work because the source code has changed.