Registry / ai-ml / inference-cli

inference-cli

JSON →
library1.5.1pypypi✓ verified 21d ago

Roboflow Inference CLI is a command-line interface designed for deploying computer vision models to various devices and environments with minimal machine learning or deployment knowledge. It provides tools to run and manage a local inference server, process data with workflows, benchmark performance, make predictions, and deploy to the cloud. The library is currently at version 1.2.2 and sees active development with frequent releases.

pip install inference-cli
INSTALL
IMPORT
SIG · INFERENCE-CLI
I
inference-cli
ai-mlpythonv1.5.1
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.5.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ timeout
1/2 runs
py 3.11
✕ timeout
1/2 runs
py 3.12
✕ dependency_conflict
1/2 runs
py 3.13
✕ no_wheel
✕ no_wheel
py 3.9
✕ timeout
1/2 runs
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

InferenceHTTPClient
from inference_sdk import InferenceHTTPClient
Used for programmatic interaction with an Inference Server (local or hosted) over HTTP.
InferencePipeline
from inference import InferencePipeline
Used for Python-native, direct inference without Docker, especially for video streams.

This quickstart demonstrates how to perform inference programmatically using the `inference_sdk.InferenceHTTPClient`. It assumes a local inference server is running (started via `inference server start` in the terminal, which requires Docker) or uses the Roboflow hosted API. It takes an image URL and a model ID, then prints the inference results. Ensure your `ROBOFLOW_API_KEY` is set as an environment variable.

import os from inference_sdk import InferenceHTTPClient # Ensure you have your Roboflow API key set as an environment variable or replace os.environ.get with your key. # You can find your API key on the Roboflow dashboard. ROBOFLOW_API_KEY = os.environ.get('ROBOFLOW_API_KEY', '') if not ROBOFLOW_API_KEY: print("Warning: ROBOFLOW_API_KEY environment variable not set. Inference may fail.") # For a quick demo without a real key, you might use a dummy value # or skip this part if you are only running a local server without Roboflow API interaction. # For proper usage, always use a real key. # 1. Start a local inference server (requires Docker to be running): # Run in your terminal: inference server start # This will typically start on http://localhost:9001 # 2. Initialize the InferenceHTTPClient client = InferenceHTTPClient( api_url="http://localhost:9001", # Or "https://serverless.roboflow.com" for hosted API api_key=ROBOFLOW_API_KEY, ) # Example image URL for inference image_url = "https://media.roboflow.com/inference/soccer.jpg" # Replace with your actual model_id (e.g., 'your-project-name/your-model-version') # You can find this on your Roboflow model's deploy tab. model_id = "soccer-players-5fuqs/1" # 3. Perform inference try: print(f"Running inference on {image_url} with model {model_id}...") results = client.infer(image_url, model_id=model_id) print("Inference successful!") # Print first few predictions for brevity if results and 'predictions' in results and len(results['predictions']) > 0: print("First 3 predictions:") for i, pred in enumerate(results['predictions'][:3]): print(f" - Class: {pred.get('class')}, Confidence: {pred.get('confidence'):.2f}") else: print("No predictions found or unexpected result format.") except Exception as e: print(f"An error occurred during inference: {e}") print("Ensure the local inference server is running ('inference server start') and the model ID/API key are correct.")
inference --version
Debug
Known issues
breakingStarting with v1.2.0, `inference-models` became the default inference engine. This change impacts performance, resource usage, and may require adjustments for GPU users. The old backend is available in opt-out mode.
fix
To continue using the old inference backend, set the environment variable `USE_INFERENCE_MODELS=False`. For GPU users, ensure `torch` and `torchvision` are installed *before* `inference-gpu` with versions compatible with your CUDA toolkit.
affects: >=1.2.0
deprecatedPython 3.9 support has been deprecated and is now effectively End-of-Life. Building projects with Python 3.9 and `inference-cli` may lead to build failures or unpatched security vulnerabilities.
fix
Upgrade your Python environment to Python 3.10 or newer (up to <3.13) as specified by the `requires_python` metadata.
affects: >=1.1.0
gotchaRunning the local inference server using `inference server start` requires Docker to be installed and running on your system. Without Docker, the server cannot be launched.
fix
Install Docker Desktop (or equivalent) for your operating system and ensure it's running before executing `inference server start`.
affects: All versions
gotchaProper GPU setup for `inference-gpu` is complex, requiring specific NVIDIA CUDA Toolkit and cuDNN installations, and careful selection of `torch` and `torchvision` versions that match your CUDA installation. Incorrect versions can lead to runtime errors or CPU-only inference.
fix
Refer to the Roboflow documentation or PyTorch installation guide to ensure you install the correct CUDA Toolkit, cuDNN, and then `torch`, `torchvision`, and `inference-gpu` packages that are compatible with each other and your hardware.
affects: All versions with GPU usage
gotchaWhen performing programmatic inference with `inference_sdk.InferenceHTTPClient` or other SDK components, an `ROBOFLOW_API_KEY` (or `API_KEY`) is typically required for authentication, especially when interacting with Roboflow's hosted services.
fix
Ensure your `ROBOFLOW_API_KEY` is set as an environment variable or passed directly to the client constructor. Obtain your API key from the Roboflow dashboard.
affects: All versions with programmatic API usage
Errors
Common errors & fixes
command not found: inference
The 'inference' command-line tool is not found in your system's PATH environment variable, meaning it's either not installed correctly or the installation directory is not accessible by your shell.
fix
Ensure `inference-cli` is installed via `pip install inference-cli` (and also `inference` and `inference-sdk` for full functionality). If it is, activate your virtual environment if using one, or add the Python site-packages script directory to your system's PATH. For example, you can often run `python -m inference --help` as an alternative to `inference --help` if `python -m` is in your PATH.
ModuleNotFoundError: No module named 'inference'
This error typically occurs when a Python script tries to `import inference`, but the `inference` Python package (or its required components) is not installed in the active Python environment.
fix
Install the necessary packages using pip: `pip install inference inference_cli inference_sdk`. If you are in a virtual environment, ensure it is activated before running the installation.
Error loading model: '{model_name}': {e}
The inference CLI encountered an issue while trying to load the specified model, which could be due to an incorrect model ID, corrupted model files, an unsupported model format, or missing dependencies required by the model.
fix
Verify the `model_id` or path you are providing is correct, ensure all necessary model files are present and uncorrupted, and check if any specific dependencies for that model type are missing. Consult the `inference-cli` documentation for supported model formats and additional setup steps for specific models.
API key not set
The `inference-cli` or an underlying model requires an API key for authentication, but the necessary environment variable (e.g., `ROBOUFLOW_API_KEY`, `OPENAI_API_KEY`) or configuration setting has not been provided or is incorrect.
fix
Set the required API key as an environment variable before running the command, for example: `export ROBOUFLOW_API_KEY='your_api_key_here'` (replace with the correct key and variable name for your specific service). Alternatively, configure it through the CLI's configuration command if available.
inference: command not found
The `inference-cli` executable is not in your system's PATH, or the installation was incomplete.
fix
Ensure `inference-cli` is installed (`pip install inference-cli`) and that your Python environment's script directory is included in your system's PATH.
Upgrade
Version history
1.5.1latest on PyPI · released Aug 28, 2026
Audit
Dependencies
DockerrequiredRequired to run the local inference server (`inference server start`) as it pulls and manages Docker images.
torchoptionalRequired for GPU inference with the `inference-models` backend. Specific CUDA-compatible versions are necessary.
torchvisionoptionalOften installed alongside `torch` for computer vision tasks, particularly with GPU inference.
pycudaoptionalA dependency for the `inference-models` backend when leveraging NVIDIA GPUs.
Agent activity
11 hits · last 30 days
node
10
Resources
inference-cli — pip install inference-cli · libregistry