Warning

This documentation is for an old version of IPython. You can find docs for newer versions here (this page newer version).

IPython extensions

A level above configuration are IPython extensions, Python modules which modify the behaviour of the shell. They are referred to by an importable module name, and can be placed anywhere you’d normally import from, or in .ipython/extensions/.

Getting extensions

A few important extensions are bundled with IPython. Others can be found on the extensions index on the wiki, and the Framework :: IPython tag on PyPI.

Extensions on PyPI can be installed using pip, like any other Python package. Other simple extensions can be installed with the %install_ext magic. The latter does no validation, so be careful using it on untrusted networks like public wifi.

Using extensions

To load an extension while IPython is running, use the %load_ext magic:

In [1]: %load_ext myextension

To load it each time IPython starts, list it in your configuration file:

c.InteractiveShellApp.extensions = [
    'myextension'
]

Writing extensions

An IPython extension is an importable Python module that has a couple of special functions to load and unload it. Here is a template:

# myextension.py

def load_ipython_extension(ipython):
    # The `ipython` argument is the currently active `InteractiveShell`
    # instance, which can be used in any way. This allows you to register
    # new magics or aliases, for example.

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.

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

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

See also

Defining custom magics

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 extensions/ within the IPython directory. This directory is added to sys.path automatically.

When your extension is ready for general use, please add it to the extensions index. We also encourage you to upload it to PyPI and use the Framework :: IPython classifier, so that users can install it with standard packaging tools.

Extensions bundled with IPython

  • octavemagic used to be bundled, but is now part of oct2py. Use %load_ext oct2py.ipython to load it.
  • rmagic is now part of rpy2. Use %load_ext rpy2.ipython to load it, and see rpy2.ipython.rmagic for details of how to use it.
  • cythonmagic used to be bundled, but is now part of cython Use %load_ext Cython to load it.