roboflow-python: the official SDK for datasets, training and hosted inference

What roboflow-python is for, and who it is not for

The package is the official Python client for Roboflow. Its README lists four jobs: create and manage projects, upload images and annotations, start training runs on Roboflow, and run inference against models hosted on Roboflow or self-hosted through Roboflow Inference. Everything it does is expressed through the same Workspace, Project and Version ontology you see in the web application, and the README states that the workspace, project and version parameters match the identifiers in app.roboflow.com and universe.roboflow.com URLs.

That framing answers the audience question. If your dataset already lives in a Roboflow workspace, the package removes the manual clicking between upload, version generation, training and prediction. If you have no Roboflow account and no intention of creating one, nothing here helps you: the library has no local training loop, no model architecture of its own, and no inference runtime bundled under the roboflow name. The separate Roboflow Inference project is where self-hosted serving lives, and the README points to it rather than folding it in.

Workspace, Project, Version: the object model that drives every call

The library mirrors the platform hierarchy directly. roboflow.Roboflow is constructed with an API key, rf.workspace() returns a workspace object, workspace.project() returns a project, and project.version() returns a version. Each level carries the operations that belong to it. A workspace can create projects, list them, upload datasets, and run active learning, which the README describes as using predictions from one project's model to upload images into a new project. A project exposes metadata, version listing, dataset version generation with preprocessing and augmentation settings, training, and image or annotation upload. A version is where deployment and prediction happen.

One detail matters for anyone writing inference code: a version can own several trained models, and version.models() returns all of them, so the README indexes the first element before calling predict. That is a design decision worth noting. Model selection is positional in the quickstart, and if a version accumulates more than one model, the index you pick determines which weights answer your request. The README does not document a name-based selector, so pinning the index in your own code is the safest reading of what is shown.

Installing roboflow-python and running a first prediction

The README requires Python 3.8 or higher, though setup.py declares python_requires=">=3.10", and the two statements do not agree. Treat the packaging metadata as the binding constraint when your environment is old. Installation is a single pip command, with an optional extra for desktop features that pulls in opencv-python.

pip install roboflow
pip install "roboflow[desktop]"

There is also a lightweight distribution, roboflow-slim, which the README says skips OpenCV, NumPy, Matplotlib and Pillow and cuts install size from roughly 400MB to roughly 50MB. It covers vision events, workspace management and the CLI only. Both packages share the same codebase and version, so the choice is about dependencies, not features you can add later without reinstalling.

Authentication comes first. roboflow.login() handles the interactive path, and passing a key directly to the constructor is the alternative the README shows.

import roboflow

rf = roboflow.Roboflow(api_key="MY_API_KEY")
workspace = rf.workspace()

From there, the README's quickstart creates an object detection project named for flowers, uploads a dataset in YOLOv8 format, and runs a prediction against a hosted model. The upload call takes dataset_path, num_workers, dataset_format and the project's licence and type. Supported formats named in the README are yolov8, yolov5 and Pascal VOC. Prediction returns a response object with a .json() method, and the example prints that dictionary.

version = project.version("VERSION_NUMBER")
model = version.models()[0]
img_url = "https://media.roboflow.com/quickstart/aerial_drone.jpeg"
predictions = model.predict(img_url, hosted=True).json()
print(predictions)

The hosted=True argument is what routes the request to Roboflow's servers rather than a local runtime, which is consistent with the package's role as a client.

Search and export: the newest workflow in the SDK

The README documents workspace.search_export(), which runs a query across a workspace and writes matching images out as a dataset in a chosen annotation format. Query syntax follows the platform's search grammar, with examples such as class:person, tag:review and the wildcard *, and format accepts coco, yolov8, yolov5 and voc. Optional arguments narrow the search to one project and set the output directory.

roboflow search-export "class:person" -f coco -d my-project -l ./my-export

The CLI entry point exists because setup.py registers roboflow=roboflow.roboflowpy:main as a console script, and the README points to CLI-COMMANDS.md for the full list. This is the part of the package that overlaps least with a typical training script: it is a data curation tool that assumes your images are already indexed in Roboflow and tagged well enough to query. If your labels are inconsistent, the query returns what the metadata says, not what the pixels show.

The dependency weight, and why roboflow-slim exists

requirements.txt shows the real cost of the default install: matplotlib, opencv-python-headless, Pillow, numpy capped below 2.4, pi-heif, pillow-avif-plugin, tqdm, typer and click, among others. The numpy cap carries a comment explaining that numpy 2.4 ships PEP 695 type statements in its stubs that mypy rejects under python_version=3.10, matching a constraint from rf-detr. That is a maintenance burden you inherit: if another package in your environment needs numpy 2.4 or newer, the resolution will conflict.

The typer pin is similarly explicit, bounded below 0.26 because that release vendors click and drops the external dependency the CLI imports. These are the kinds of constraints that appear when a client library also ships a command line tool and image utilities. roboflow-slim is the escape hatch, and the README names embedded devices, CI pipelines and serverless environments as the intended users. If you only need to create projects or manage a workspace from a build script, the slim package avoids dragging OpenCV into a container that will never decode an image.

Where roboflow-python is the wrong tool

The clearest failure mode is expecting it to work without the service. Every operation in the README flows through an authenticated Roboflow account: project creation, dataset upload, version generation, training and hosted prediction. There is no documented offline path, and the README does not describe what happens to queued uploads when the API is unreachable. If your requirement is that training runs on your own hardware with no external dependency, this package does not meet it, and the self-hosted story runs through the separate Roboflow Inference repository instead.

The second limitation is data residency. Uploading a dataset means the images leave your environment, and the README does not document a private-storage option beyond the project licence setting, which it notes as "private" for paid customers. Teams with regulatory constraints on where training data may sit should treat that as a blocker rather than a configuration detail.

The third is version drift between the README and the packaging metadata. The stated Python floor of 3.8 conflicts with python_requires=">=3.10" in setup.py, so an environment on 3.9 will fail at install time despite what the README says. Small, but it is the kind of discrepancy that costs an afternoon.

How it compares with training frameworks you already use

The natural comparison is with a framework like TensorFlow or PyTorch. The difference is not quality, it is layer. A framework gives you model definitions, a training loop, gradient handling and a local inference runtime, all of which run on your machine. roboflow-python gives you none of those. It gives you authenticated calls that create a project, push a dataset, trigger a training run on Roboflow's infrastructure, and query a hosted model endpoint. The README's own quickstart uploads YOLOv10 weights through version.deploy(model_type="yolov10", model_path=..., filename="weights.pt"), which shows the intended relationship: you train wherever you like, then hand the artifact to Roboflow for hosting and prediction.

That makes the two complementary rather than competing. A team using PyTorch for experimentation can use roboflow-python to manage the dataset and serve the result. A team that wants to own the entire pipeline end to end, including the serving layer, gets nothing from this package and should look at Roboflow Inference or a plain framework deployment. The package also assumes the Roboflow annotation and versioning model is how you want to work, which is a workflow commitment, not just a library choice.

Maintenance, licensing and what to check before you pin it

The repository is not archived, and the last push was on 2026-09-08. Recent releases are v1.4.0 on 2026-07-23, v1.4.1 on 2026-08-18, described in the release list as "Annotation administration SDK & CLI", and v1.4.2 on 2026-09-01. That cadence suggests the API surface is still moving, particularly around annotation administration, so pinning an exact version in requirements.txt is more sensible than a floating range if your code depends on specific method signatures.

The package is Apache-2.0 and setup.py carries the matching classifier. That covers the client code. It does not cover the Roboflow service, your account terms, or the models you train and host there, and the README does not describe those terms. The project licence you pass to create_project is a separate field with its own consequences, and the README shows MIT and private as accepted values without explaining the rest of the set. If licence compatibility matters to your organisation, read the platform terms rather than inferring them from the SDK's licence.

For development, the repository ships a Makefile with style and check_code_quality targets running ruff format, ruff check and mypy over the roboflow directory, and pyproject.toml configures ruff with a long ignore list. The test suite lives under tests/, and the README points contributors to the package developer documentation at roboflow.github.io/roboflow-python for a full library reference.

Editorial conclusion

Adopt roboflow-python if your images and annotations already live in a Roboflow workspace, or if you want project creation, dataset upload and hosted inference behind one API key. Do not adopt it if you need a self-contained training or inference stack with no platform dependency, or if you cannot store data outside your own infrastructure; the package is a client for Roboflow's service, and the README does not document any offline mode. Before committing, verify that the workspace, project and version identifiers you plan to use resolve correctly with rf.workspace(), workspace.project() and project.version(), and check the licence field you pass to create_project, since the README shows both MIT and private as accepted values.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. roboflow/roboflow-python on GitHub