Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
timeout
glibcpy 3.10–3.920 runs
timeout
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
InferenceHTTPClient
✓ from inference_sdk import InferenceHTTPClient
✗ from inference import InferenceHTTPClient
This quickstart demonstrates how to perform object detection using Roboflow's cloud inference service. It initializes `InferenceHTTPClient` with an API key and then sends an image URL for inference. Ensure your `ROBOFLOW_API_KEY` and `ROBOFLOW_PROJECT_VERSION` environment variables are set.
import os
from inference import InferenceHTTPClient
# IMPORTANT: Set ROBOFLOW_API_KEY, ROBOFLOW_WORKSPACE, and ROBOFLOW_PROJECT_VERSION
# as environment variables for actual use. Get them from your Roboflow dashboard.
# For local testing, you may uncomment and set these directly:
# os.environ["ROBOFLOW_API_KEY"] = "YOUR_API_KEY"
# os.environ["ROBOFLOW_WORKSPACE"] = "YOUR_WORKSPACE_ID"
# os.environ["ROBOFLOW_PROJECT_VERSION"] = "YOUR_PROJECT_ID/YOUR_VERSION" # e.g., "my-project/1"
api_key = os.environ.get("ROBOFLOW_API_KEY", "")
workspace = os.environ.get("ROBOFLOW_WORKSPACE", "")
project_version = os.environ.get("ROBOFLOW_PROJECT_VERSION", "your_project/1") # Replace with your actual project/version
if not api_key:
print("WARNING: ROBOFLOW_API_KEY environment variable not set. Inference may fail.")
if not workspace:
print("WARNING: ROBOFLOW_WORKSPACE environment variable not set. This may not be critical for HTTPClient but is for other features.")
if project_version == "your_project/1":
print("WARNING: ROBOFLOW_PROJECT_VERSION environment variable not set. Using placeholder.")
try:
# Initialize the client for cloud inference
client = InferenceHTTPClient(
api_url="https://detect.roboflow.com", # Or https://infer.roboflow.com for multi-model workflows
api_key=api_key
)
# Example image (replace with a real image path or URL)
image_url = "https://i.ibb.co/L5hY63C/roboflow-example.jpg"
# Perform inference
print(f"Performing inference on {image_url} using model {project_version}...")
result = client.infer(
image_path=image_url,
model_id=project_version,
# confidence=0.5, # Optional: set confidence threshold
# overlap=0.3, # Optional: set NMS overlap threshold
)
print("\nInference successful:")
# The result object has a .json() method for the raw API response
# print(result.json(indent=2))
# Accessing structured predictions
if result and result.predictions:
print(f"Found {len(result.predictions)} predictions.")
for i, pred in enumerate(result.predictions[:3]): # Print details for first 3 predictions
print(f" Prediction {i+1}: Class='{pred.class_name}', Confidence={pred.confidence:.2f}, Box=({pred.x},{pred.y},{pred.width},{pred.height})")
else:
print("No predictions found or unexpected result structure.")
except Exception as e:
print(f"\nAn error occurred during inference: {e}")
if "401: Unauthorized" in str(e) or "authentication" in str(e):
print("HINT: Check your ROBOFLOW_API_KEY. It might be missing or invalid.")
elif "404: Not Found" in str(e) and ("Model" in str(e) or "project" in str(e)):
print("HINT: Check your ROBOFLOW_PROJECT_VERSION. The model might not exist or the version is wrong.")
else:
print("HINT: Refer to the Roboflow Inference documentation for troubleshooting.")
inference --version
Debug
Known issues
breakingStarting with v1.2.0, the `inference-models` engine became the default backend for running predictions. While the old inference backend is still available in opt-out mode, users might experience changes in behavior or performance if they relied on the previous default.fixReview the `inference-models` documentation for any required code adjustments or explicitly opt-out to use the old backend if necessary (refer to official documentation for opting out).
affects: >=1.2.0
deprecatedPython 3.9 support was deprecated starting with the v1.1.0 release. Users on Python 3.9 might encounter issues or lack of future updates.fixUpgrade your Python environment to Python 3.10 or higher. The library officially supports Python >=3.10, <3.13.
affects: >=1.1.0
gotchaFor GPU acceleration using `inference-gpu`, PyTorch and torchvision with CUDA support must be installed *prior* to installing `inference-gpu`. Simply `pip install inference-gpu` will not install PyTorch automatically for GPU.fixInstall `torch`, `torchvision`, and `torchaudio` with the correct CUDA version first (e.g., `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118`), then install `inference-gpu` (`pip install inference-gpu`).
affects: All versions with `inference-gpu`
gotchaAuthentication requires `ROBOFLOW_API_KEY` to be set, typically as an environment variable or passed directly to the `InferenceHTTPClient`. Missing or incorrect keys will result in 'Unauthorized' errors.fixEnsure `ROBOFLOW_API_KEY` is correctly set in your environment or passed as an argument to `InferenceHTTPClient`. You can obtain your API key from your Roboflow dashboard settings.
affects: All versions
gotchaWhen using `InferenceHTTPClient.infer()`, the `model_id` parameter expects a string in the format `project_id/version_number` (e.g., 'my-project/1'). Incorrect formatting or non-existent project/version will lead to 'Not Found' errors.fixVerify the `model_id` string matches your Roboflow project ID and model version exactly. You can find this information on your Roboflow project page.
affects: All versions
Upgrade
Version history
1.3.1latest on PyPI · released Jun 12, 2026
Audit
Dependencies
torchoptionalRequired for GPU acceleration when using the `inference-gpu` package, and must be installed separately before `inference-gpu`.
torchvisionoptionalRequired for GPU acceleration when using the `inference-gpu` package, and must be installed separately before `inference-gpu`.
torchaudiooptionalOften installed alongside PyTorch for completeness, though not always directly used by `inference-gpu` for core vision tasks.