Design with Python

Writing protocols in Python requires some up-front design before seeing your liquid handling automation in action. At a high-level, writing protocols with the Opentrons API looks like:

  1. Write a Python protocol
  2. Test the code for errors
  3. Repeat steps 1 & 2
  4. Calibrate labware on robot
  5. Run your protocol

These sets of documents aim to help you get the most out of steps 1 & 2, the “design” stage.

Python for Beginners

If Python is new to you, we suggest going through a few simple tutorials to acquire a base understanding to build upon. The following tutorials are a great starting point for working with the Opentrons API (from

  1. Hello World
  2. Variables and Types
  3. Lists
  4. Basic Operators
  5. Conditions
  6. Loops
  7. Functions
  8. Dictionaries

After going through the above tutorials, you should have enough of an understanding of Python to work with the Opentrons API and start designing your experiments!

Working with Python

Currently, we recommend writing your protocols in one of two ways:

Text Editor

Using a popular and free code editor, like Sublime Text 3, is a common method for writing Python protocols. Download onto your computer, and you can now write and save Python scripts.


Make sure that when saving a protocol file, it ends with the .py file extension. This will ensure the App and other programs are able to properly read it.

For example,

Jupyter Notebook

For a more interactive environment to write and debug using some of our API tools, we recommend using Jupyter Notebook. To begin, just install Anaconda, which comes with Jupyter Notebook.

Once installed, launch Jupyter Notebook, and install the Opentrons API by doing the following:

  1. Create a new Python notebook
  2. Run the command !pip install --upgrade opentrons in a cell
  3. Restart your notebook’s Kernel, and API will be installed


Be sure to download the Python 3.7 version if Anaconda, and Python 2.7 will not work with the Opentrons API.