Impulse

Impulse is a command line tool for exploring the imports in a Python package.

Running it will open up the graph in a browser window, along with download links for SVG and PNG.

Screenshot

Installation

1. Install Impulse using your favorite Python package manager. E.g., with pip:

   pip install impulse
   

2. Ensure the package under test is importable, e.g. by changing your working directory to the one containing the package, or installing it via a Python package manager.

One liner using uv tool

If you use uv you can run it with this one-liner, without needing to install anything.

uv tool run --with=PACKAGE impulse drawgraph MODULE_NAME

Command overview

There is currently only one command.

drawgraph

Usage: impulse drawgraph [OPTIONS] MODULE_NAME

Options:
  --show-import-totals   Label arrows with the number of imports they
                         represent.
  --show-cycle-breakers  Identify a set of dependencies that, if removed,
                         would make the graph acyclic, and display them as
                         dashed lines.
  --format [html|dot]    Output format (default to html).
  --force-console        Force the use of the console output.
  --help                 Show this message and exit.

Draw a graph of the dependencies within any installed Python package or subpackage.

The graph shows the relationship between all the immediate children of the package. An arrow indicates that there is at least one import by the child (or any of its descendants) from the subpackage where the arrow points.

The graph visualization is opened in a browser.

Example

impulse drawgraph django.db

In this example, there is an arrow from .models to .utils. This is because (along with one other import) django.db.models.constraints imports django.db.utils.DEFAULT_DB_ALIAS.

Example with import totals

impulse drawgraph django.db --show-import-totals

Here you can see that there are two imports from modules within django.db.models of modules within django.db.utils.

Example with cycle breakers

impulse drawgraph django.db --show-cycle-breakers

Here you can see that two of the dependencies are shown as a dashed line. If these dependencies were to be removed, the graph would be acyclic. To decide on the cycle breakers, Impulse uses the nominate_cycle_breakers method provided by Grimp.

Output formats

By default, Impulse renders the graph as an interactive HTML page and opens it in your browser. You can change the output format using the --format option.

HTML format (default)

impulse drawgraph django.db --format html

Generates an HTML page with an interactive graph visualization, including download links for SVG and PNG. This is the default format when no --format option is specified.

DOT format

impulse drawgraph django.db --format dot

Outputs the graph in DOT format, which can be used with Graphviz or other tools that support this format. This is useful for custom rendering or integration with other systems.

For example, to generate a PNG using Graphviz:

impulse drawgraph django.db --format dot | dot -Tpng -o graph.png

Redirecting output

When you redirect the output to a file or pipe it to another command, Impulse automatically switches from opening a browser to printing to the console:

impulse drawgraph django.db > graph.html

If you want to force console output even when running interactively (e.g., for scripting purposes), use the --force-console flag:

impulse drawgraph django.db --force-console