The pygrace project is a set of tools designed to act as an interface between the Python programming language and the Grace plotting tool.

pygrace allows users to create complex Grace files from within Python.

It is intended to:

pygrace was originally created by Dean Malmgren, Mike Stringer, and members of the Amaral Lab. When they decided to let pygrace die a slow death, its maintainance was taken over by Daniel Stouffer and the Stouffer Lab.

To get started with pygrace, see the installation guide.

This tutorial is meant to help with installation of pygrace, and give new users an idea of how pygrace is structured. After reading this brief document, the next step for learning to use pygrace is to go through the examples that are located in the pygrace Examples directory.


As pygrace is still young, the only method yet available to install it is to check out the source code from the git repository at the Github page. The next section describes how to do so.

Installing a development version

To clone the pygrace repository, change to a directory where you want to save the code and type:

git clone

To install pygrace, all you need to do is enter into the pygrace directory you just created and run

cd pygrace
python install

By default, Python will attempt to install pygrace in the global Python site-packages directory. If you don't have permissions to do this (or prefer not to install pygrace globally), you can install it locally by adding the --user option:

python install --user

You can test that python can find the pygrace package by opening an interactive python prompt and typing:

import PyGrace

If no error is raised, then installation was succesful!

Getting started

pygrace was designed so that, “anything you can do in Grace, you can do in pygrace.” The best way to get started is to go through the examples in the Examples directory. Each example is fully commented. You may also find the following three documents helpful:

By refering to these diagrams and going through the examples, you can develop a sense of how to use pygrace. Please let us know what you think and report bugs using the GitHub page.


Here are some examples of the types of figures that you can create with pygrace templates. If you are interested in contributing a screenshot of a figure made in pygrace templates, contact us.

If you use pygrace in a scientific publication, please let us know and we will add a link to your publication on this page (where everybody will see it).