Roboflow Python mirrors the URL you already have open

Workspace, project, version, straight from the URL

The library is structured on the same ontology as the application, which is the single decision that makes it feel obvious to use.

A workspace, a project and a version are the three objects, and each is constructed from the identifier you would find in the address bar at app.roboflow.com or universe.roboflow.com. There is no separate naming scheme, no slug to translate, and no id to look up in a settings page.

What each object does follows from that position in the hierarchy. The workspace creates projects, lists them, and performs active learning, which is the operation where predictions from one project's model become uploads to another project. The project retrieves its own metadata, lists versions, generates a new dataset version with preprocessing and augmentation settings, trains a model, and accepts uploads of images and annotations. The version downloads in whatever model format you ask for, can be trained on Roboflow, and is where an external model of your own gets deployed.

Project types are the four the platform distinguishes: object detection, classification, instance segmentation and semantic segmentation. Project licences are public or private, and the quickstart notes that private is only available for paid customers.

Two packages, one codebase, 400MB or 50MB

There are two distributions and they are not editions of each other.

The full package installs the whole client. The lightweight one, installed under a different name, exists for the case where you need vision events, workspace management and the command line, but never touch image processing, inference or training. It skips the heavy dependencies, which the documentation names as OpenCV, NumPy, Matplotlib and Pillow, and takes the install from roughly 400MB to roughly 50MB.

The stated targets for it are embedded devices, continuous integration pipelines and serverless environments, which is the right list: those three are exactly the places where a 400MB dependency tree is a deployment problem rather than an inconvenience.

The important guarantee is that both packages share the same codebase and the same version. There is no feature parity question and no divergence to track, because installing the full package includes everything the slim one has. The repository carries the split in two places, a separate slim requirements file and a separate slim setup script, which is what keeps the dependency lists from drifting into different worlds.

There is also a third path, installing from source into a fresh virtual environment, which is what contributors use. The entry point for the first path is one command:

pip install roboflow

The HEIC extra is opt-in for a licence reason

One extra is missing on purpose, and the reason is a licensing boundary rather than a missing feature.

Local decoding of HEIC and HEIF images is available through an opt-in extra, which pulls in a HEIF plugin for the imaging library. The reason it is not in the base install is stated plainly: that plugin's binary wheels bundle an encoder whose licence makes the wheels GPL-2.0, so shipping them by default would impose GPL terms on every user of an Apache-licensed package.

The workaround is simple and is spelled out in the documentation. You only need the extra if you are decoding HEIC files yourself, for example to run prediction on a local HEIC photo. Uploading HEIC images works without it, because the server does the decoding.

The other optional extra, for desktop features, pins a specific computer-vision build exactly rather than with a range, which is the opposite decision for a different reason: the desktop path depends on a particular version's behaviour rather than merely being heavy.

So the two extras bracket the problem. One is heavy and pinned; one is light but licence-encumbered.

Search and export is one call, not an upload loop

Retrieving a subset of a workspace is a first-class operation in the package rather than something you assemble from a listing call and a download call.

The workspace method takes a query, an annotation format, and optionally a project and an output directory. The query language is the same one the platform uses elsewhere, with field-prefixed terms such as a class filter or a tag filter, and a wildcard for everything. The format argument accepts COCO and several YOLO and VOC variants, which is what makes the output a ready-to-use dataset rather than a bag of images.

Both the project and the location are optional. Omitting the project searches the whole workspace; supplying it narrows the export. Omitting the location lets the library choose, which is the behaviour you want in a notebook and not the behaviour you want in a pipeline.

The same operation exists on the command line with the same four pieces of information, so a script that exports a filtered dataset does not need a Python file. That pairing is the pattern through the whole package: anything you can do in the library has a command line form documented separately, and anything you can do in the command line can be scripted without leaving the shell.

EU data residency changes the backend, not the code

The package serves two regions and the difference between them is worth understanding before you write the authentication code.

You select the EU data-residency platform at login time, either with a region flag on the command line or by setting an environment variable before running anything, which is the form intended for continuous integration and other environment-driven setups:

roboflow auth login --region eu

The consequence that will bite you if you skip it: EU and US use separate authentication backends. An API key issued by the US app is not accepted by the EU side, and you need a key obtained from the EU application. So a region mistake surfaces as an authentication failure rather than as a clear regional error, which is why setting the variable once in the environment is the safer habit.

Everything else in the package is identical across regions. Same objects, same methods, same export formats. The region is a property of the session you authenticate into rather than a mode the library branches on.

The requirements file explains every pin in a comment

The dependency list is unusually well annotated, and reading the comments tells you more about the project than the version numbers do.

NumPy is capped below 2.4, and the comment says why: that release ships type statements in its stubs that the type checker rejects under the target Python version, and the same ceiling is applied in a related detector project so the two agree.

The computer-vision dependency has an exact pin relaxed into a range, with a reference to the issue, because pinning it exactly broke installs downstream. That is a deliberate choice to prefer compatibility over reproducibility for that one package.

The CLI framework is capped too, for a structural reason: the version that would be allowed vendors another dependency the CLI imports directly, so taking it would silently remove an external library the code relies on.

Beyond pinning, there is a lint policy worth noting. The linter runs with its strictest rule set selected and then ignores a long explicit list of families, which is a different posture from selecting a curated subset: it means a new rule is on by default and has to be argued out. The same configuration bans the image and numeric libraries as module-level imports in the library code, forcing them behind functions, and the quality target runs the formatter check, the linter and the type checker together.

Two ways to authenticate, and a version read from source

Authentication is either an interactive login call or a constructed client with a key, and the first is for a person at a terminal while the second is for code.

The interactive path is a single call that prompts and stores credentials. The programmatic path constructs the client object with an API key inline, which is what a script or a notebook uses, and where the key comes from is the reader's business, usually an environment variable.

Installing the package also gives you a command line entry point, and the documentation for it is a separate file rather than a section of the README. That entry point covers the same functionality as the library for the operations that make sense without code, including authentication with a region, search and export, and workspace and project management.

The packaging itself is old-fashioned in one telling way: the version string is not written in the setup file. It is read out of the package's own init file with a regular expression at build time, so there is exactly one place to bump. Two other artifacts in the repository tree suggest how the project is consumed rather than run: a development container definition and a dev Dockerfile for contributors, and a citation file for anyone referencing the work.

Editorial conclusion

Roboflow Python fits a team that already keeps its datasets and models on Roboflow and wants the same operations from a script, a notebook or a pipeline, and it fits a constrained environment through the slim package. It does not fit someone who wants to store data locally, since every useful call goes to the service. Before you build on it, decide which package you need, because the full one drags in OpenCV and Matplotlib for a workflow that may never decode an image, and set the region variable before your first authenticated call if you need EU data residency, since the two regions use separate authentication backends and the wrong key fails in a way that looks like an auth problem rather than a region problem.

Frequently asked questions

Official sources

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