# roboflow

> Official Python package for working with the Roboflow API

- **URL**: https://www.freshcrate.ai/projects/roboflow
- **Author**: Roboflow
- **Category**: Developer Tools
- **Latest version**: `v1.3.9` (2026-05-29)
- **License**: Unknown
- **Source**: https://github.com/roboflow-ai/roboflow-python
- **Language**: Python
- **GitHub**: 559 stars, 124 forks
- **Registry**: pypi (`roboflow`)
- **Tags**: `pypi`

## Description

<div align="center">
  <p>
    <a align="center" href="" target="_blank">
      <img
        width="100%"
        src="https://github.com/roboflow/roboflow-python/assets/37276661/528ed065-d5ac-4f9a-942e-0d211b8d97de"
      >
    </a>
  </p>

  <br>

  [notebooks](https://github.com/roboflow/notebooks) | [inference](https://github.com/roboflow/inference) | [autodistill](https://github.com/autodistill/autodistill) | [collect](https://github.com/roboflow/roboflow-collect)  | [supervision](https://github.com/roboflow/supervision)

  <br>

  [![version](https://badge.fury.io/py/roboflow.svg)](https://badge.fury.io/py/roboflow)
  [![downloads](https://img.shields.io/pypi/dm/roboflow)](https://pypistats.org/packages/roboflow)
  [![license](https://img.shields.io/pypi/l/roboflow)](https://github.com/roboflow/roboflow-python/blob/main/LICENSE.md)
  [![python-version](https://img.shields.io/pypi/pyversions/roboflow)](https://badge.fury.io/py/roboflow)

</div>

# Roboflow Python Package

[Roboflow](https://roboflow.com) provides everything you need to build and deploy computer vision models. `roboflow-python` is the official Roboflow Python package. `roboflow-python` enables you to interact with models, datasets, and projects hosted on Roboflow.

With this Python package, you can:

1. Create and manage projects;
2. Upload images, annotations, and datasets to manage in Roboflow;
3. Start training vision models on Roboflow;
4. Run inference on models hosted on Roboflow, or Roboflow models self-hosted via [Roboflow Inference](https://github.com/roboflow/inference), and more.

The Python package is documented on the [official Roboflow documentation site](https://docs.roboflow.com/api-reference/introduction). If you are developing a feature for this Python package, or need a full Python library reference, refer to the [package developer documentation](https://roboflow.github.io/roboflow-python/).

## 💻 Installation

You will need to have `Python 3.8` or higher set up to use the Roboflow Python package.

Run the following command to install the Roboflow Python package:

```bash
pip install roboflow
```

For desktop features, use:

```bash
pip install "roboflow[desktop]"
```


<details>
  <summary>Lightweight install (roboflow-slim)</summary>

  If you only need vision events, workspace management, and the CLI (no image processing, inference, or training), install the lightweight package:

  ```bash
  pip install roboflow-slim
  ```

  This skips heavy dependencies like OpenCV, NumPy, Matplotlib, and Pillow, reducing install size from ~400MB to ~50MB. Useful for embedded devices, CI pipelines, and serverless environments.

  Both packages share the same codebase and version. `pip install roboflow` includes everything.
</details>

<details>
  <summary>Install from source</summary>

  You can also install the Roboflow Python package from source using the following commands:

  ```bash
  git clone https://github.com/roboflow-ai/roboflow-python.git
  cd roboflow-python
  python3 -m venv env
  source env/bin/activate
  pip install .
  ```
</details>

<details>
  <summary>Command line tool</summary>

  By installing roboflow python package you can use some of its functionality in the command line (without having to write python code).
  See [CLI-COMMANDS.md](CLI-COMMANDS.md)
</details>


## 🚀 Getting Started

To use the Roboflow Python package, you first need to authenticate with your Roboflow account. You can do this by running the following command:

```python
import roboflow
roboflow.login()
```

<details>
<summary>Authenticate with an API key</summary>

You can also authenticate with an API key by using the following code:

```python
import roboflow

rf = roboflow.Roboflow(api_key="")
```

[Learn how to retrieve your Roboflow API key](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key).

</details>

## Quickstart

Below are some common methods used with the Roboflow Python package, presented concisely for reference. For a full library reference, refer to the [Roboflow API reference documentation](https://docs.roboflow.com/api-reference).

```python
import roboflow

# Pass API key or use roboflow.login()
rf = roboflow.Roboflow(api_key="MY_API_KEY")

workspace = rf.workspace()

# creating object detection model that will detect flowers
project = workspace.create_project(
    project_name="Flower detector",
    project_type="object-detection", # Or "classification", "instance-segmentation", "semantic-segmentation"
    project_license="MIT", # "private" for private projects, only available for paid customers
    annotation="flowers" # If you plan to annotate lillys, sunflowers, etc.
)

# upload a dataset
workspace.upload_dataset(
    dataset_path="./dataset/",
    num_workers=10,
    dataset_format="yolov8", # supports yolov8, yolov5, and Pascal VOC
    project_license="MIT",
    project_type="object-detection"
)

version = project.version("VERSION_NUMBER")

# upload model weights - yolov10
version.deploy

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `v1.3.9` | 2026-05-29 | High | ## Model evaluations SDK & CLI  Wraps the public `/{workspace}/model-evals` REST surface so users can read evaluation results — mAP, confidence sweep, per-class performance, confusion matrix, vector clusters, per-image stats, recommendations — from Python and from the CLI without hitting the API directly.  ### SDK - `Workspace.evals(project=None, version=None, model=None, status=None, limit=None)` — list evals as `ModelEval` instances pre-populated with metadata from the list response. - ` |
| `v1.3.8` | 2026-05-06 | High | ## Device Management — SDK + CLI  Adds Python SDK and CLI bindings for the external Deployments / Device Management API (shipped in [#469](https://github.com/roboflow/roboflow-python/pull/469)). 1:1 with the documented public routes. PATCH `/config`, stream commands, device delete, and fleet-groups CRUD are intentionally out of scope.  ### SDK  - **`Workspace.devices()`** — list all devices in the workspace. - **`Workspace.device(id)`** — fetch a single device by id. - **`Workspace.creat |
| `v1.3.7` | 2026-04-29 | High | ## Soft-delete / Trash support — SDK + CLI  Mirrors the soft-delete and Trash features added to the Roboflow web app ([roboflow/roboflow#11131](https://github.com/roboflow/roboflow/pull/11131)). Deleting a project, version, or workflow now moves it to Trash with a 30-day retention window (and cancels any in-flight training jobs); items can be restored within that window. Companion docs: [roboflow-dev-reference#5](https://github.com/roboflow/roboflow-dev-reference/pull/5).  ### SDK  - **`Project. |
| `v1.3.5` | 2026-04-23 | High | ## What's Changed * Remove direct publishing via twine (ENT-1128) by @rvirani1 in https://github.com/roboflow/roboflow-python/pull/459 * Async zip upload flow for Workspace.upload_dataset (DATAMAN-240) by @digaobarbosa in https://github.com/roboflow/roboflow-python/pull/456 * Validate task type before model upload by @leeclemnet in https://github.com/roboflow/roboflow-python/pull/457 * feat: support text-image-pairs (VLM) hosted inference by @joaomarcoscrs in https://github.com/roboflow/robo |
| `1.3.3` | 2026-04-21 | Low | Imported from PyPI (1.3.3) |
| `v1.3.3` | 2026-04-15 | High | ### New Features  **Vision Events SDK & CLI** (#451) - New SDK support for the Vision Events API: write single/batch events, query with pagination, list use cases, and upload images. - New `roboflow vision-events` CLI command group with subcommands: `write`, `write-batch`, `query`, `use-cases`, `upload-image`. - Thin-client design — no client-side validation, so new event types and fields work without a SDK update.  **`roboflow-slim` package** (#451) - New lightweight `roboflow-slim` ins |
| `v1.3.1` | 2026-04-03 | Medium | This release rewrites the Roboflow CLI from the ground up to serve as the canonical machine interface for the Roboflow platform. Every command now supports `--json` for structured output, follows a consistent `noun verb` pattern, and provides actionable error messages to make Roboflow accessible to coding agents, CI/CD pipelines, and automation workflows.  ### Highlights  **🏗️ Modular CLI architecture** — The monolithic CLI has been decomposed into 18 handler modules organized by resource ( |
| `v1.2.16` | 2026-03-03 | Low | At the workspace level you can now search and delete images.  Sample code using both: ```  """Delete all orphan images matching a workspace-level search query.  Usage:     python tests/manual/demo_search_delete.py """  from roboflow import Roboflow  QUERY = "project:false" PAGE_SIZE = 100 DELETE_BATCH_SIZE = 1000 DRY_RUN = False  # set to False to actually delete  WORKSPACE_SLUG = "workspace"   def main():     rf = Roboflow()     workspace = rf.workspace(WORKSPACE_SLUG) |
| `v1.2.15` | 2026-02-25 | Low | We now make it available to the python sdk to upload metadata when starting upload |
| `v1.2.14` | 2026-02-18 | Low | We provide a new method to export images and annotations based on search queries. It replicates the Asset Library Download functionality on the CLI. |

## Citation

- HTML: https://www.freshcrate.ai/projects/roboflow
- Markdown: https://www.freshcrate.ai/projects/roboflow.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/roboflow/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._
