IPython Documentation

Table Of Contents

Previous topic

Overview of the IPython configuration system

Next topic

autoreload

This Page

IPython extensions

Configuration files are just the first level of customization that IPython supports. The next level is that of extensions. An IPython extension is an importable Python module that has a a few special function. By defining these functions, users can customize IPython by accessing the actual runtime objects of IPython. Here is a sample extension:

# myextension.py

def load_ipython_extension(ipython):
    # The ``ipython`` argument is the currently active
    # :class:`InteractiveShell` instance that can be used in any way.
    # This allows you do to things like register new magics, plugins or
    # aliases.

def unload_ipython_extension(ipython):
    # If you want your extension to be unloadable, put that logic here.

This load_ipython_extension() function is called after your extension is imported and the currently active InteractiveShell instance is passed as the only argument. You can do anything you want with IPython at that point.

The load_ipython_extension() will be called again is you load or reload the extension again. It is up to the extension author to add code to manage that.

Useful InteractiveShell methods include define_magic(), push() (to add variables to the user namespace) and drop_by_id() (to remove variables on unloading).

You can put your extension modules anywhere you want, as long as they can be imported by Python’s standard import mechanism. However, to make it easy to write extensions, you can also put your extensions in os.path.join(self.ipython_dir, 'extensions'). This directory is added to sys.path automatically.

Using extensions

There are two ways you can tell IPython to use your extension:

  1. Listing it in a configuration file.
  2. Using the %load_ext magic function.

To load an extension called myextension.py add the following logic to your configuration file:

c.InteractiveShellApp.extensions = [
    'myextension'
]

To load that same extension at runtime, use the %load_ext magic:

In [1]: %load_ext myextension

To summarize, in conjunction with configuration files and profiles, IPython extensions give you complete and flexible control over your IPython setup.

Extensions bundled with IPython