Getting Started

Using the Darwin cli is the fastest way to upload / download vast amounts of data to your dataset. It can also help you import and export annotations in various formats.

The cli is part of the darwin-py package which also includes our Python SDK. This section of documentation will focus on the command line tool aspects.


pip install darwin-py

Once installed, darwin will be available from the command line.


Python Versions

Darwin-py has been tested for python >= 3.8 and <= 3.10 , while older or newer versions might work they are not supported.


Team and Dataset Slugs

You will often be asked to enter a team-slug or dataset-slug as a parameter. If you are unsure on how to generate this then you can use the Slugify Python library.


To perform remote operations on Darwin you first need to authenticate. Authentication requires a team-specific API-key.
If you do not already have a Darwin account, you can contact us and we can set one up for you.

To start the authentication process:

$ darwin authenticate
API key: ***********
Make example-team the default team? [y/N] y
Datasets directory [~/.darwin/datasets]: 
Authentication succeeded.

You will be then prompted to enter your API-key, whether you want to set the corresponding team as default and finally the desired location on the local file system for the datasets of that team. This process will create a configuration file at ~/.darwin/config.yaml. This file will be updated with future authentications for different teams.



The API key rights selected when requesting the key determine which commands in the SDK are allowed. If the key has insufficient permissions for an action an error will be shown: Insufficient permissions or Invalid API key.

See it in action!