Python Package
Navigating the pip package
Most Roboflow users will interact with the platform through their web UI, but often times, workflows require Python integrations. The gold-standard for python packages is pip provided by PyPi.
The python package, over time, will be able to handle all actions you can perform on the web UI programmatically; although, for now a select number of operations are able to be performed. Please request any functionality you might need on the roboflow-python repository.

You can either install Roboflow through the PyPi package:
pip install roboflow
or manually through the GitHub:
git clone https://github.com/roboflow-ai/roboflow-python.git
cd roboflow-python
python3 -m venv
source venv/bin/activate
pip3 install -r requirements.txt

The Python Package allows you to:
  1. 1.
    List information about workspaces, projects, and versions.
  2. 2.
    Upload images to your projects.
  3. 3.
    Perform inference with specific model versions.
  4. 4.
    Visualize, and save predictions that you've made on the model.

Looking for your projectID on the app.roboflow.com website or want a jumpstart with some code scaffolding? A pre-built code snippet can be found within your workspace using the following steps:
  1. 1.
    select the export button on the generated dataset you need to work with
2. Select show download code
3. Copy-paste the code snippet into your code editor of choice. Note: this can also be an effective method to find your projectID.

Find the Workspace ID, Project/Model ID, and Version Number in the URL for your project.
Example project link (Public/Community workspace): https://app.roboflow.com/mohamed-traore-2ekkp/face-detection-mik1i/7

Methods follow the following cascading pattern:
  • Roboflow()
  • Roboflow().workspace()
  • Roboflow().workspace().project()

Everything in the package works through the Roboflow() object. You must pass your private API key to the object, which can be found under the settings of your workspace. Full instructions for obtaining your API Key can be found here.
from roboflow import Roboflow
# obtaining your API key: https://docs.roboflow.com/rest-api#obtaining-your-api-key
rf = Roboflow(api_key="YOUR_PRIVATE_API_KEY")

Workspace details such as name, URL, and a list of projects can be found the workspace() method:
workspace = rf.workspace()
# name
workspace.name
# URL
workspace.url
# Projects
workspace.projects()

Workspace objects can provide reference to a specific project using the project(projectID) method. See step 3 of Quick start sample code direct from your project for an easy way to find the projectID.
project = workspace.project("YOUR_PROJECT_ID")
You can upload a local image to this project by doing:
project.upload("UPLOAD_IMAGE.jpg")
# if you want to attempt reuploading image on failure
project.upload("UPLOAD_IMAGE.jpg"), num_retry_uploads=3)

Next, if you want to access the versions of a specific project:
all_versions = project.versions()# or
version = project.version(1)
If you've trained a model on this version, you can perform inference on the model with either a local or hosted image:
model = version.model
prediction = model.predict("YOUR_IMAGE.jpg", confidence=40, overlap=30)# or
prediction_hosted = model.predict("https://www.yourimageurl.com", hosted=True, confidence=40, overlap=30)
You can save a visualization of the prediction.
prediction.plot()
prediction.save(output_path="predictions.jpg")
Or access your model's prediction as JSON.
prediction.json()# or
prediction_hosted.json()

To install dependencies, pip install roboflow
Setting up the logic for object counts on a single target class:
from roboflow import Roboflow
import os, sys, re, glob
# obtaining your API key: https://docs.roboflow.com/rest-api#obtaining-your-api-key
rf = Roboflow(api_key="INSERT_PRIVATE_API_KEY")
workspace = rf.workspace("INSERT_WORKSPACE_ID")
project = rf.workspace("INSERT_WORKSPACE_ID").project("INSERT_MODEL/PROJECT_ID")
# replace REPLACE_WITH_MODEL_VERSION_NUM with your model version number
version = project.version(REPLACE_WITH_MODEL_VERSION_NUM)
model = version.model
def count_object_occurances(predictions, target_class):
"""
Helper method to count the number of objects in an image for a given class
:param predictions: predictions returned from calling the predict method
:param target_class: str, target class for object count
:return: dictionary with target class and total count of occurrences in image
"""
object_counts = {target_class : 0}
for prediction in predictions:
if prediction['class'] in target_class:
object_counts[prediction['class']] += 1
return object_counts
Example: Setting up object counting logic, with target class of 'face' (API Key removed for security)
Run model inference and object counting on a single image file:
# perform inference on the selected image
predictions = model.predict("YOUR_IMAGE.jpg") # or
## uncomment the following line to run inference on a hosted image
# prediction_hosted = model.predict("https://www.yourimageurl.com", hosted=True)
## replace target_class with name of target_class
## example, target class is 'face': count_object_occurances(predictions, 'face')
class_counts = count_object_occurances(predictions, target_class)
print(predictions, class_counts)
print('\n')
Example: Object counting on a single image file
Run model inference and object counting on a folder (directory) of image files:
raw_data_location = "INSERT_PATH_TO_IMG_DIRECTORY"
raw_data_extension = ".jpg" # e.g jpg, jpeg, png
globbed_files = glob.glob(raw_data_location + '/*' + raw_data_extension)
## replace target_class with name of target_class
## example, target class is 'face': count_object_occurances(predictions, 'face')
for img_file in globbed_files:
predictions = model.predict(img_file)
class_counts = count_object_occurances(predictions, target_class)
print(predictions, class_counts)
print('\n')
Example: Object counting on an entire folder (directory) of images

To install dependencies, pip install roboflow
active_learning.py
from roboflow import Roboflow
# obtaining your API key: https://docs.roboflow.com/rest-api#obtaining-your-api-key
rf = Roboflow(api_key="INSERT_PRIVATE_API_KEY")
workspace = rf.workspace()
raw_data_location = "INSERT_PATH_TO_IMAGES"
raw_data_extension = ".jpg"
# replace * with your model version number for inference
inference_endpoint = ["INSERT_MODEL_ID", *]
upload_destination = "INSERT_MODEL_ID"
# set the conditionals values as necessary for your active learning needs
conditionals = {
"required_objects_count" : 1,
"required_class_count": 1,
"target_classes": [],
"minimum_size_requirement" : float('-inf'),
"maximum_size_requirement" : float('inf'),
"confidence_interval" : [10,90],
}
# filtering out images for upload by similarity is available for paid plans
# contact the Roboflow team for access: https://roboflow.com/sales
# conditionals = {
# "required_objects_count" : 1,
# "required_class_count": 1,
# "target_classes": [],
# "minimum_size_requirement" : float('-inf'),
# "maximum_size_requirement" : float('inf'),
# "confidence_interval" : [10,90],
# "similarity_confidence_threshold": .3,
# "similarity_timeout_limit": 3
# }
workspace.active_learning(raw_data_location=raw_data_location,
raw_data_extension=raw_data_extension,
inference_endpoint=inference_endpoint,
upload_destination=upload_destination,
conditionals=conditionals)

Just like the Roboflow REST API, our vision for the Roboflow Python pip package is to eventually reach feature parity with our web UI so you can automate and integrate any part of your Roboflow workflow into your own codebase.
Copy link
On this page
Installation
Overview
Quick start sample code direct from your project
Methods
Customize Inference Image Results
Object Counting
Active Learning
To Be Continued