Introduction

When you edit a Python module during an interactive session, the already imported module object does not automatically refresh. The standard solution is to reload the module explicitly, and the best tool for that in modern Python is importlib.reload.

Why a Normal import Is Not Enough

Python caches imported modules in sys.modules. That means if you run import mymodule again after editing the file, Python usually reuses the already loaded module object instead of reading the file again.

import mymodule
import mymodule  # does not reload changed source code

That behavior is good for performance and consistency, but it surprises people during iterative development.

Use importlib.reload

The normal way to refresh a module is to import it once and then reload it explicitly.

1import importlib
2import mymodule
3
4mymodule = importlib.reload(mymodule)

This re-executes the module's top-level code and updates its contents in the current process.

It is the right default for interactive shells, local experimentation, and quick debugging sessions.

A Common Trap: from module import name

Reloading the module does not automatically refresh names that were imported directly into the local namespace.

1from mymodule import greet
2import importlib
3import mymodule
4
5mymodule = importlib.reload(mymodule)
6greet()  # may still refer to the old function object

If you want reloads to behave predictably, prefer:

import mymodule
mymodule.greet()

That way, the function lookup happens through the module object that you reloaded.

Jupyter and IPython Have a Better Workflow

If you work in IPython or Jupyter, the autoreload extension can save a lot of manual effort.

%load_ext autoreload
%autoreload 2

With %autoreload 2, IPython attempts to reload imported modules before each execution. That is convenient for notebook-driven exploration where source files change frequently.

It is not magic, but it is often the smoothest workflow for interactive development.

Reloading Has Limits

importlib.reload re-executes the module, but it does not rewind every object in the universe that may already refer to old classes or functions.

Examples of tricky cases include:

• existing class instances created before the reload
• other modules that imported symbols directly
• cached decorators or registries built from old objects
• module-level state that accumulates across reloads

So reloading is best for lightweight iteration, not as a substitute for restarting the process indefinitely.

A Small Example

Suppose mymodule.py contains:

def greet():
    print("hello")

Interactive session:

1import importlib
2import mymodule
3
4mymodule.greet()
5# edit mymodule.py so greet prints a different message
6
7mymodule = importlib.reload(mymodule)
8mymodule.greet()

That is the simplest reliable reimport pattern.

When Restarting Is the Better Choice

If the module maintains complex global state, open file handles, thread pools, or long-lived object graphs, restarting the interpreter may be safer than repeated reloads.

Reloading is great when you are iterating on pure functions or small classes. It is less reliable when the module is deeply entangled with application state.

A practical rule is:

• small stateless module edits: reload
• complex application state changes: restart

Common Pitfalls

The most common mistake is expecting import module to reread the file after edits. It usually will not.

Another common issue is using from module import name and then wondering why the imported symbol still points to the old object after reloading. Developers also often keep reloading a stateful module when restarting the interpreter would actually be safer and clearer.

Summary

• Use importlib.reload(module) to refresh a module during an interactive Python session.
• Re-importing with plain import usually does not reload changed source code.
• Prefer import module over from module import name when you expect to reload.
• In Jupyter, %autoreload 2 can automate much of the workflow.
• For heavily stateful modules, restarting the interpreter is often safer than repeated reloads.