Encord Python SDK

Common errors

• ModuleNotFoundError: No module named 'python_dotenv'

  cause The `python-dotenv` package is not installed, but it is required if you are using a `.env` file for local environment variable management.
  fix Install the missing dependency: `pip install python-dotenv` or `pip install encord python-dotenv`.

• Authentication or API call failed: Invalid private key provided.

  cause The SSH private key used for authentication is either incorrect, malformed, or has expired. The client cannot establish a secure connection.
  fix Verify that your SSH private key is correct, unexpired, and properly formatted. Ensure you are using the correct key for your Encord region (EMEA or US) and that it has the necessary permissions.

• Failed to load image/video from remote storage

  cause This error often indicates a misconfigured Cross-Origin Resource Sharing (CORS) policy on your cloud storage bucket (e.g., AWS S3, GCP, Azure), preventing Encord from accessing the media.
  fix Update the CORS policy for your remote storage bucket to allow access from Encord's domains. Consult your cloud provider's documentation for specific instructions on setting up CORS.

• requests.exceptions.ReadTimeout: HTTPConnectionPool(...) Read timed out.

  cause This timeout typically occurs when `user_client.get_project()` is called on an exceptionally large project, and the default network timeout is exceeded while fetching project data.
  fix Increase the timeout for your Encord client or consider fetching project data in smaller, more manageable queries if the API supports it. Check the Encord documentation for client configuration options related to timeouts.

Warnings

• gotcha Datasets cannot be deleted via the Python SDK or API; they must be removed directly through the Encord platform web interface.
  Fix: Access the Encord platform GUI to manage dataset deletion.
• gotcha When working with remote storage (AWS S3, GCP, Azure), Cross-Origin Resource Sharing (CORS) policies must be correctly configured for images or videos to load properly in the Encord application. Failure to do so will result in loading errors.
  Fix: Ensure a valid CORS policy is applied to your remote storage bucket, allowing Encord's domains. Consult provider-specific documentation for CORS setup (e.g., AWS S3 bucket policy).
• gotcha Calling `user_client.get_project()` on very large projects can lead to timeouts.
  Fix: Consider increasing the timeout setting for your Encord client instance, or break down operations into smaller queries if possible.
• deprecated Some 'Label / Activity logs' functionalities within project management are marked as deprecated.
  Fix: Refer to the latest Encord documentation for updated methods or alternatives for accessing label and activity logs.
• gotcha Video re-encoding issues (e.g., 'ghost frames' from negative timestamps, unexpected behavior with audio frames, variable frame rates) can cause annotation misalignment.
  Fix: Utilize Encord's platform or SDK re-encoding functions to process videos. The platform detects and warns about such issues, offering re-encoding solutions (e.g., dropping audio, re-encoding video frames, converting formats).

Install

• pip install encord Basic Installation
• pip install encord python-dotenv With .env file support

Imports

• EncordUserClient

  from encord.user_client import EncordUserClient

• StorageLocation

  from encord.orm.dataset import StorageLocation

• LabelRowV2

  from encord.objects import LabelRowV2

Quickstart

Initializes the Encord client using an SSH private key from environment variables (supporting both EMEA and US deployments) and then lists the first 5 accessible datasets. A private key must be generated from the Encord web app and set as an environment variable (ENCORD_KEY or ENCORD_US_KEY).

import os
from encord.user_client import EncordUserClient

# For EMEA clients, use 'ENCORD_KEY'. For US clients, use 'ENCORD_US_KEY'.
# Replace with your actual private key content or set the environment variable.
# Example: export ENCORD_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
private_key = os.environ.get('ENCORD_KEY', os.environ.get('ENCORD_US_KEY', ''))

if not private_key:
    print("Error: Encord private key not found in environment variables (ENCORD_KEY or ENCORD_US_KEY).")
    print("Please set the environment variable or replace the placeholder in the code.")
else:
    try:
        user_client = EncordUserClient.create_with_ssh_private_key(private_key)
        print("Successfully authenticated with Encord.")

        # Example: List up to 5 datasets accessible by the user
        datasets = user_client.list_datasets(page_size=5)
        if datasets:
            print("\nFirst 5 datasets:")
            for ds in datasets:
                print(f"  - {ds.title} (ID: {ds.dataset_hash})")
        else:
            print("No datasets found.")

    except Exception as e:
        print(f"Authentication or API call failed: {e}")