Roboflow Python SDK

1.3.1 · active · verified Thu Apr 09

The Roboflow Python package (version 1.3.1) is the official SDK for interacting with the Roboflow API, enabling programmatic access for tasks such as dataset management, image upload, model training, and inference. It is actively developed, with recent updates including a comprehensive rewrite of the command-line interface and enhanced capabilities for workspace-level asset management.

Warnings

breaking The v1.3.1 release introduced a complete rewrite of the Roboflow CLI. Users who programmatically invoked CLI commands (e.g., via `subprocess`) will find command structures, argument patterns (`noun verb`), and output formats (e.g., `--json` output) have fundamentally changed. While the Python SDK's core programmatic interface (`roboflow.Roboflow` class) remains stable, direct CLI interaction patterns are now significantly different.
Fix: Review the updated Roboflow CLI documentation for the new command structure and output formats. Adapt any scripts or automation workflows that relied on the older CLI behavior.
gotcha When working with HEIF (.heic/.heif) image formats, users on Python 3.9 might encounter issues due to a dependency (`pi_heif`) dropping support for Python 3.9 around Roboflow v1.2.13. This is a dependency-related incompatibility rather than a core Roboflow SDK issue.
Fix: Upgrade your Python environment to 3.10 or newer if you need to process HEIF images with the Roboflow SDK. Alternatively, avoid HEIF images on Python 3.9.
gotcha For security and best practice, your Roboflow API key should always be loaded from environment variables (e.g., `os.environ["ROBOFLOW_API_KEY"]`) rather than being hardcoded directly into your scripts. Hardcoding keys can lead to security vulnerabilities if your code is exposed.
Fix: Set your `ROBOFLOW_API_KEY` as an environment variable. When initializing, use `rf = Roboflow(api_key=os.environ.get("ROBOFLOW_API_KEY", ""))` to safely retrieve it.

Install

pip install roboflow Install Roboflow

Imports

Roboflow
```
from roboflow import Roboflow
```

Quickstart

Initializes the Roboflow client and demonstrates connecting to a workspace. It's recommended to store your API key in an environment variable for security.

import os
from roboflow import Roboflow

# Ensure your Roboflow API key is set as an environment variable (recommended)
# os.environ["ROBOFLOW_API_KEY"] = "YOUR_API_KEY"

# Initialize Roboflow with your API key
# Replace 'YOUR_ROBOFLOW_API_KEY' with os.environ.get("ROBOFLOW_API_KEY", "") for production
rf = Roboflow(api_key=os.environ.get("ROBOFLOW_API_KEY", ""))

# Example: Get a workspace (replace 'your-workspace-id' with your actual workspace ID)
# You can often omit the ID if you only have one workspace associated with your API key
try:
    workspace = rf.workspace("your-workspace-id") 
    print(f"Connected to workspace: {workspace.name}")
except Exception as e:
    print(f"Could not connect to workspace: {e}. Check your API key and workspace ID.")

# Example: List projects in the workspace
# if 'workspace' in locals():
#     projects = workspace.projects()
#     print(f"Projects in workspace: {[p.name for p in projects]}")

view raw JSON →