pypath command-line interface in pypath-magic v0.3

pypath-magic provides a simple interface for adding modules and packages to your Python path.

Unlike modifications to sys.path, this allows you to easily modify your Python path across sessions. Unlike modifications to environment variables, this doesn't require you to explain to users, students, and colleagues how to modify environment variables.

In addition to the namesake IPython magic, version 0.3 of pypath-magic adds a command-line interface (CLI) that resembles the IPython interface. After installing the latest version (pip install pypath_magic), you'll have access to a pypath command in your favorite terminal/shell.

You might also want to take a look at the original quick-start article for version 0.2. The rest of this article just translates the IPython workflow from that article to the new CLI.

Why would you modify your Python path?

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:

$ ls  # Helper files are in the same directory as the main script.

Now, if you want to execute a main script that needs to wrangle some data and plot the results, then you can just run:

$ python

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

$ ls                   # Main file is local ...

$ ls path/to/my-utils  # ...but utilities are somewhere else.

$ python

Traceback (most recent call last):
  File "", line 1, in <module>
    import plot_helpers
ImportError: No module named plot_helpers

Quickfix: sys.path

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

import sys

from plot_helpers import plot_slope_marker

But, if you want to use these utilities elsewhere, you'll have to jump through these hoops every time you use it.

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. Sure, you can package up your code properly, but for most people, that's a significant leap in effort.

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 the pypath CLI

After installing the latest version (pip install pypath_magic), you'll have access to a pypath command in your favorite terminal/shell.

List the custom paths

To list all the custom paths added by pypath, open a terminal and type:

$ pypath

When you get started, you won't have anything there, so you'll get:

No user paths are defined.
See `pypath -h` for usage information.

Add to your Python path

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

$ cd path/to/my-utils

$ ls

$ pypath add
Added u'/absolute/path/to/my-utils' to path.

$ pypath
0. /absolute/path/to/my-utils

Now you can reuse those helper functions from anywhere:

from plot_helpers import plot_slope_marker

Deleting one of your custom paths

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

$ cd path/to/my-utils

$ pypath delete
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 list-all:

$ pypath list-all


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:

$ pypath add path/to/useful-modules
Added u'/absolute/path/to/useful-modules' to path.

$ pypath add /absolute/path/to/stuff
Added u'/absolute/path/to/stuff' to path.

$ pypath add path/to/things
Added u'/absolute/path/to/things' to path.

$ 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:

$ pypath delete 1
Deleted u'/absolute/path/to/stuff' from path.

$ pypath
0. /absolute/path/to/useful-modules
1. /absolute/path/to/things

$ pypath delete path/to/useful-modules
Deleted u'/absolute/path/to/useful-modules' from path.

$ 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+

Or if you want to go direct to the source:

$ git clone
$ cd pypath-magic
$ python 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