Skip to main content

The Opentrons API is a simple framework designed to make writing automated biology lab protocols easy.

Project description

The Opentrons API is a simple framework designed to make writing automated biology lab protocols for the Opentrons OT-2 easy.

This package can be used to simulate protocols on your computer without connecting to a robot. Please refer to our Full API Documentation for detailed instructions on how to write and simulate your first protocol.

This package is now for use with the Opentrons OT-2 only. For the software needed to run an Opentrons OT-1, please see versions.

Simulating Protocols

To simulate a protocol using this package, you can use the console script opentrons_simulate, which is installed when this package is installed from pip. For detailed information on how to run the script, run opentrons_simulate --help. In general, however, simulating a protocol is as simple as running opentrons_simulate.exe C:\path\to\protocol on Windows or opentrons_simulate /path/to/protocol on OSX or Linux.

The simulation script can also be invoked through python with python -m opentrons.simulate /path/to/protocol.

This also provides an entrypoint to use the Opentrons simulation package from other Python contexts such as an interactive prompt or Jupyter. To simulate a protocol in python, open a file containing a protocol and pass it to opentrons.simulate.simulate:

import opentrons.simulate
protocol_file = open('/path/to/')

The function will either run and return or raise an exception if there is a problem with the protocol.


The module has a lot of configuration, some of which is only relevant when running on an actual robot, but some of which could be useful during simulation. When the module is first imported, it will try and write configuration files in ~/.opentrons/config.json (C:\Users\%USERNAME%\.opentrons\config.json on Windows). This contains mostly paths to other configuration files and directories, most of which will be in that folder. The location can be changed by setting the environment variable OT_API_CONFIG_DIR to another path. Inividual settings in the config file can be overridden by setting environment variables named like OT_API_${UPPERCASED_VAR_NAME} (for instance, to override the serial_log_file config element you could set the environment variable OT_API_SERIAL_LOG_FILE to a different path).

Note On Versions

This API is for locally simulating protocols for the OT 2 without connecting to a robot. It no longer controls an OT 1.

Version 2.5.2 was the final release of this API for the OT 1. If you want to download this API to use the OT 1, you should download it with

pip install opentrons==2.5.2

For APIs between 2.5.2 and 3.7.0, there is no PyPI package available. Those APIs should be installed by cloning this repo and following the instructions in the Development Setup section of and the API readme.

Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release. See tutorial on generating distribution archives.

Built Distribution

opentrons-4.2.0-py2.py3-none-any.whl (913.8 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page