Python Package

Product Forum Computer Vision Datasets Computer Vision Models
Search…
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.
Installation
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
Overview
The Python Package allows you to:
1.List information about workspaces, projects, and versions.
2.Upload images to your projects.
3.Perform inference with specific model versions. 
4.Visualize, and save predictions that you've made on the model. 
Quick start sample code direct from your project
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.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.
​
​
Finding your project information manually:
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​
Workspace: mohamed-traore-2ekkp
Project/Model ID: face-detection-mik1i
(Model/Dataset/Project) Version Number: 7
API Key: https://docs.roboflow.com/rest-api#obtaining-your-api-key​
NOTE: This project link is only accessible by those invited to the workspace as team members, the default functionality for all Roboflow projects.
This project link, for Roboflow Universe, is publicly viewable for Roboflow Public/Community workspaces. Accessing the project with this link does not allow for edits of your personal project, but rather downloads of generated dataset versions; viewing the images Added to the Dataset (Dataset column in the Annotation Workflow); performing Dataset Search on images Added to the Dataset; and testing of the model with the Deploy tab if a dataset version has been trained with Roboflow Train.
​How to Share a Public Project​
Methods
Methods follow the following cascading pattern:
Roboflow()
Roboflow().workspace()
Roboflow().workspace().project()
Roboflow()
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()
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()
project()
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)
version()
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()
​Customize Inference Image Results​
Object Counting
​https://github.com/roboflow-ai/roboflow-object-counting​
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
Active Learning
​How to Implement Active Learning | Roboflow's Python Package for Active Learning​
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)
To Be Continued
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.
Format
Frequently Asked Questions (FAQ)
Last modified 13d ago
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
Installation

Overview

Quick start sample code direct from your project

Finding your project information manually:

Methods

Roboflow()

workspace()

project()

version()

​Customize Inference Image Results​

Object Counting

Active Learning

To Be Continued
