Installation and Setup

Penman releases are available on PyPI and the source code is on GitHub. Users of Penman will probably want to install from PyPI using pip as it is the easiest method and it makes the penman command available at the command line. Developers and contributors of Penman will probably want to install from the source code.


The Penman package runs with Python 3.6 and higher versions, but otherwise it has no dependencies beyond Python’s standard library.

Some development tasks, such as unit testing, building the documentation, or making releases, have additional dependencies. See Installing from Source for more information.


Installing from PyPI

Install the latest version from PyPI using pip (using a virtual environment is recommended):

$ pip install penman

After running the above command, the penman module will be available in Python and the penman command will be available at the command line.

Installing from Source

Developers and contributors of the Penman project may wish to install from the source code using one of several “extras”, which are given in brackets after the package name. The available extras are:

  • test – install dependencies for unit testing

  • doc – install dependencies for building the documentation

  • dev – install dependencies for both of the above plus those needed for publishing releases

When installing from source code, the -e option is also useful as any changes made to the source code after the install will be reflected at runtime (otherwise one needs to reinstall after any changes). The following is how one might clone the source code, create and activate a virtual environment, and install for development:

$ git clone
$ cd penman/
$ python3 -m venv env
$ source env/bin/activate
(env) $ pip install -e .[dev]


Unit Testing with pytest

The unit tests can be run with pytest from the project directory of the source code:

(env) $ pytest

For testing multiple Python versions, a tool like tox can automate the creation and activation of multiple virtual environments.

Type-checking with Mypy

The Penman project heavily uses PEP 484 and PEP 526 type annotations for static type checking. The code can be type-checked using Mypy:

(env) $ mypy penman

Style-checking with Flake8

Flake8 is used for style checking with the following checks disabled:

  • E241 – large data descriptions are easier to read with whitespace

  • W503 – binary operators should appear after a line break

(env) $ flake8 --ignore=E241,W503 penman