%pypath: An IPython magic for manipulating your Python path

Edit: Now with support for Python 3!

You're a pragmatic Python developer, so you extract the logically related bits of your code into functions and group those functions together into modules.

Now, how do you actually import those modules? If you're in the directory containing those modules, you're good to go:

In [1]: %ls  # Desired files are in the same directory.

In [2]: from plot_helpers import plot_slope_marker

If, instead, those files are located elsewhere, you might get something like this:

In [3]: %ls path/to/my-utils  # Desired files are somewhere else.

In [4]: from plot_helpers import plot_slope_marker
ImportError                               Traceback (most recent call last)
<ipython-input-141-1d0fef5fa475> in <module>()
----> 1 from plot_helpers import plot_slope_marker

ImportError: No module named plot_helpers

Quickfix: sys.path

The quick fix here is to append to sys.path:

In [3]: import sys

In [4]: sys.append('path/to/my-utils')

In [5]: from plot_helpers import plot_slope_marker

But, the next time you fire up python, you get the same ImportError we saw above.

Persistent changes to your path

To make persistent changes to your Python path, you'll have to tweak your PYTHONPATH or figure out how to add '*.pth' files to your site-packages directory.

These solutions are annoying for most users and downright intimidating to newer developers. With %pypath, you can easily manipulate your Python path from IPython.

How to use pypath_magic

The pypath_magic module adds an IPython magic (err... Jupyter magic?) command for easily manipulating your Python path.

Load the extension

To use the %pypath magic command, just load the extension from an IPython session:

In [1]: %load_ext pypath_magic

List the custom paths

After loading, you will have access to the %pypath magic. You can type:

In [2]: %pypath

to list all the custom paths added by pypath-magic. When you get started, you won't have anything there.

Add to your Python path

To add some custom paths, just change to a directory and call %pypath -a:

In [3]: %cd path/to/my-utils

In [4]: %ls

In [5]: %pypath -a
Added u'/absolute/path/to/my-utils' to path.

In [6]: %pypath
0. /absolute/path/to/my-utils

Now you can reuse those helper functions from anywhere:

In [7]: from plot_helpers import plot_slope_marker

Changes to your Python path will persist across IPython sessions, and those paths will be available outside of IPython.

Deleting one of your custom paths

If you later want to delete a directory from your path, just use %pypath -d:

In [8]: %cd path/to/my-utils

In [9]: %pypath -d
Deleted u'/absolute/path/to/my-utils' from path.

List everything in your Python path

You can also list your entire Python path with %pypath -l:

In [10]: %pypath -l


Adding and deleting using arguments

Finally, you can manipulate paths---without changing to those directories---by passing arguments to the add and delete commands.

First we add paths using relative or absolute directory paths:

In [11]: %pypath -a path/to/useful-modules
Added u'/absolute/path/to/useful-modules' to path.

In [12]: %pypath -a /absolute/path/to/stuff
Added u'/absolute/path/to/stuff' to path.

In [13]: %pypath -a path/to/things
Added u'/absolute/path/to/things' to path.

In [14]: %pypath
0. /absolute/path/to/useful-modules
1. /absolute/path/to/stuff
2. /absolute/path/to/things

Notice those numbers in the list above. We can use those indices to delete paths, or we can delete using string paths:

In [15]: %pypath -d 1
Deleted u'/absolute/path/to/stuff' from path.

In [16]: %pypath
0. /absolute/path/to/useful-modules
1. /absolute/path/to/things

In [17]: %pypath -d path/to/useful-modules
Deleted u'/absolute/path/to/useful-modules' from path.

In [18]: %pypath
0. /absolute/path/to/things

How it works

The basic idea is really simple: The pypath command just maintains a custom *.pth file in your site-packages directory. Altering that file alters the paths in the Python path. Since this is a custom *.pth file, you don't have to worry about screwing up packages installed by other means.


To install using pip, just type the following in a terminal:

$ pip install pypath_magic

Or if you're feeling lucky:

$ pip install git+https://github.com/tonysyu/pypath-magic

Or if you want to go direct to the source:

$ git clone https://github.com/tonysyu/pypath-magic.git
$ cd pypath-magic
$ python setup.py install


  • Python 2.7/3.4 (older versions probably work, but this is not tested)
  • IPython >= 1.0


New BSD (a.k.a. Modified BSD). See LICENSE file in this directory for details.


comments powered by Disqus