Python protocols

Standard labware

See the API documentation for instructions on how to load labware in a Python protocol.

You will need to know the labware's API name to load it. The API name can be easily copied from the labware's listing in the Labware Library.

Custom labware in APIv2 protocols

Custom labware needs to be added through the Opentrons App before it can be used in a Python APIv2 protocol.

Note: the Opentrons protocol development team uses Python APIv2 to write custom protocols.

You should already have a .json file exported from Labware Creator or provided to you by the Opentrons protocol development team.

To add the custom labware definition:

  1. In the Opentrons App, go to More > Custom labware and click Add labware. A file browser will open.

  2. Select the .json file representing your custom labware definition.

  3. You should see your new labware in the Custom Labware List.

You will need to do this on each computer through which you upload protocols that use that custom labware.

Note: if you make any changes to the .json file on your local computer, you will need to add it to the App again to overwrite the old definition.

After adding the labware through the Opentrons App, protocols can reference it using its API name, like standard labware. See the API documentation for details.

Custom labware in APIv1 protocols

Python APIv1 protocols can only use custom labware created with the labware.create()  function. To take advantage of custom labware created through Labware Creator, you must migrate your protocol to APIv2. See Switching Your Protocols From API Version 1 to Version 2.

Using labware.create() custom labware in APIv2 protocols

The labware.create() APIv1 function has been removed in APIv2.

Labware already created through labware.create() is not available to APIv2 protocols. To use such labware in an APIv2 protocol, it must be recreated with the Labware Creator and added through the Opentrons App, as shown above.

Protocol Designer protocols

Standard and custom labware

Protocol Designer can use any labware in the Labware Library.

When you click Add Labware while hovering over a slot in the deck, you'll be presented with a list of labware to choose from. You'll also have the option to import a custom labware definition you've made with our Labware Creator.

Jupyter Notebook

Standard labware

As with regular Python protocols, use the load_labware()  function to load labware. See the API documentation for details.

Custom labware

To use custom labware in a Jupyter notebook, you need to take some extra steps.

1. Uploading the definition

  1. On the Jupyter Notebook homepage, click Upload.

  2. Select the .json file corresponding to your custom labware definition.

  3. The .json file will appear in the file list. Next to its entry, click Upload again.

2. Loading the labware

Once you have the custom labware definition file in the Jupyter notebook directory, you can access it from within a Python notebook. Loading the labware for use in the Python Protocol API involves:

  1. Loading the contents of the uploaded .json file representing the labware definition.

  2. Parsing the JSON text into a Python dictionary.

  3. Passing the dictionary to load_labware_from_definition() to get the labware object.

For example:

import json
import opentrons.execute
protocol = opentrons.execute.get_protocol_api()
with open('InGen 96 Well Plate 200 µL.json') as labware_file:
    labware_def = json.load(labware_file)
well_plate = protocol.load_labware_from_definition(labware_def, 1)

Note that the file name 'InGen 96 Well Plate 200 µL.json' is needed instead of the API name 'ingen_96_wellplate_200ul'.

Did this answer your question?