V7 Darwin Python SDK
⚡️ Official library to annotate, manage datasets, and models on V7's Darwin Training Data Platform. ⚡️
Darwin-py can both be used from the command line and as a python library.
Main functions are (but not limited to):
- Client authentication
- Listing local and remote datasets
- Create/remove datasets
- Upload/download data to/from remote datasets
- Direct integration with PyTorch dataloaders
- Extracting video artifacts
Support tested for python 3.10 - 3.13
🏁 Installation
pip install darwin-py
You can now type darwin in your terminal and access the command line interface.
If you wish to use the PyTorch bindings, then you can use the ml flag to install all the additional requirements
pip install darwin-py[ml]
If you wish to use video frame extraction, then you can use the ocv flag to install all the additional requirements
pip install darwin-py[ocv]
If you wish to use video artifacts extraction, then you need to install FFmpeg
To run test, first install the test extra package
pip install darwin-py[test]
Configuration
Retry Configuration
The SDK includes a retry mechanism for handling API rate limits (429) and server errors (500, 502, 503, 504). You can configure the retry behavior using the following environment variables:
DARWIN_RETRY_INITIAL_WAIT: Initial wait time in seconds between retries (default: 60)DARWIN_RETRY_MAX_WAIT: Maximum wait time in seconds between retries (default: 300)DARWIN_RETRY_MAX_ATTEMPTS: Maximum number of retry attempts (default: 10)
Example configuration:
# Configure shorter retry intervals and fewer attempts
export DARWIN_RETRY_INITIAL_WAIT=30
export DARWIN_RETRY_MAX_WAIT=120
export DARWIN_RETRY_MAX_ATTEMPTS=5
The retry mechanism will automatically handle:
- Rate limiting (HTTP 429)
- Server errors (HTTP 500, 502, 503, 504)
For each retry attempt, you'll see a message indicating the type of error and the wait time before the next attempt.
Development
See our development and QA environment installation recommendations here
Usage as a Command Line Interface (CLI)
Here you can find V7 labs doc on the CLI usage
Once installed, darwin is accessible as a command line tool.
A useful way to navigate the CLI usage is through the help command -h/--help which will
provide additional information for each command available.
Client Authentication
To perform remote operations on Darwin you first need to authenticate. This 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.
Listing local and remote datasets
Lists a summary of local existing datasets
$ darwin dataset local
NAME IMAGES SYNC_DATE SIZE
mydataset 112025 yesterday 159.2 GB
Lists a summary of remote datasets accessible by the current user.
$ darwin dataset remote
NAME IMAGES PROGRESS
example-team/mydataset 112025 73.0%
Create/remove a dataset
To create an empty dataset remotely:
$ darwin dataset create test
Dataset 'test' (example-team/test) has been created.
Access at https://darwin.v7labs.com/datasets/579
The dataset will be created in the team you're authenticated for.
To delete the project on the server:
$ darwin dataset remove test
About to delete example-team/test on darwin.
Do you want to continue? [y/N] y
Upload/download data to/from a remote dataset
Uploads data to an existing remote project. It takes the dataset name and a single image (or directory) with images/videos to upload as parameters.
The -e/--exclude argument allows to indicate file extension/s to be ignored from the data_dir.
e.g.: -e .jpg
For videos, the frame rate extraction rate can be specified by adding --fps <frame_rate>
Supported extensions:
- Video files: [
.mp4,.bpm,.mov,.avi,.mkv,.hevc,.pdf,.dcm,.nii,.nii.gz,.ndpi,.rvgformats]. - Image files [
.jpg,.jpeg,.png,.jfif,.tif,.tiff,.qtiff,.bmp,.svs,.webp,.JPEG,.JPG,.BMPformats].
$ darwin dataset push test /path/to/folder/with/images
100%|████████████████████████| 2/2 [00:01<00:00, 1.27it/s]
Before a dataset can be downloaded, a release needs to be generated:
$ darwin dataset export test 0.1
Dataset test successfully exported to example-team/test:0.1
This version is immutable, if new images / annotations have been added you will have to create a new release to included them.
To list all available releases
$ darwin dataset releases test
NAME IMAGES CLASSES EXPORT_DATE
example-team/test:0.1 4 0 2019-12-07 11:37:35+00:00
And to finally download a release.
$ darwin dataset pull test:0.1
Dataset example-team/test:0.1 downloaded at /directory/choosen/at/authentication/time .
Usage as a Python library
Here you can find V7 labs doc on the usage as Python library
The framework is designed to be usable as a standalone python library.
Usage can be inferred from looking at the operations performed in darwin/cli_functions.py.
A minimal example to download a dataset is provided below and a more extensive one can be found in
from darwin.client import Client
client = Client.local() # use the configuration in ~/.darwin/config.yaml
dataset = client.get_remote_dataset("example-team/test")
dataset.pull() # downloads annotations and images for the latest exported version
Follow this guide for how to integrate darwin datasets directly in PyTorch.
Release files for darwin-py 3.6.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| darwin_py-3.6.2.tar.gz | 262.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| darwin_py-3.6.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 622.0 kB
Release files / darwin_py-3.6.2.tar.gz
| Download URL | darwin_py-3.6.2.tar.gz |
|---|---|
| Size | 262.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b608dbf27194b8407959ec2a6ebf6b5edf7096d41c27ab918c6652d8c9d87c71
|
|
BLAKE2b-256 checksum How to use checksums |
e015f8f992c1bc3048e2781ef5c47b0fb3181e6bb569a786cb59fbb8d43014eb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency logRelease files / darwin_py-3.6.2-py3-none-any.whl
| Download URL | darwin_py-3.6.2-py3-none-any.whl |
|---|---|
| Size | 359.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
61d5e0ec30ffa532836e3debc83667c69daca855ac25803f3b20bcc66279ce5e
|
|
BLAKE2b-256 checksum How to use checksums |
26e590be5c8714c5fcf8011cece8388b059d1b0859057ecd8ec6270783fa0b14
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency log
