Blackfire Python SDK

2026.3.0 verified Fri May 01 auth: no python

The Blackfire Python SDK enables profiling and performance monitoring of Python applications with Blackfire.io. It supports automatic instrumentation, manual probe API, and integration with frameworks like Django, Flask, Symfony, and more. Current version: 2026.3.0. Released on a regular cadence following Blackfire updates.

pip install blackfire

Common errors

error ImportError: No module named 'blackfire' ↓

cause The blackfire package is not installed in the current Python environment.

fix

Run 'pip install blackfire' in your environment.

error blackfire.exceptions.BlackfireException: Unable to connect to Blackfire agent ↓

cause The Blackfire agent is not running or the socket path is incorrect.

fix

Ensure the Blackfire agent is running and set the BLACKFIRE_AGENT_SOCKET environment variable to the correct socket path. Alternatively, set BLACKFIRE_CLIENT_ID and BLACKFIRE_CLIENT_TOKEN to use the cloud API directly.

error AttributeError: module 'blackfire' has no attribute 'BlackfireProbe' ↓

cause Using an older version of blackfire where BlackfireProbe was not available or imported incorrectly.

fix

Upgrade to blackfire>=2022.0.0 using 'pip install --upgrade blackfire'. Ensure import is 'from blackfire import BlackfireProbe'.

error TypeError: __init__() got an unexpected keyword argument 'signature' ↓

cause The 'signature' parameter was removed in a newer version of the BlackfireProbe.

fix

Remove the 'signature' argument. Use the 'name' or 'transaction_name' parameter instead. Check the documentation for the current API.

Warnings

breaking Blackfire dropped support for Python 2.7 and 3.5 in version 2022.x. Ensure you are using Python 3.6+. ↓

fix Upgrade to Python 3.6+ and install blackfire>=2022.0.0.

gotcha The 'blackfire' package must be installed in the Python environment being profiled. For profiling web frameworks, use the framework-specific middleware (e.g., DjangoMiddleware) which may require additional configuration. ↓

fix Always install blackfire in the same environment as your application. For web apps, add the middleware and set the 'BLACKFIRE_AGENT_SOCKET' environment variable if using a local agent.

deprecated The 'blackfire.sdk' module is deprecated. All functionality is now in top-level 'blackfire'. ↓

fix Replace 'from blackfire.sdk import ...' with 'from blackfire import ...'.

gotcha When using the 'generate_instrumentation' function, ensure your environment has the BLACKFIRE_AGENT_SOCKET set if you are using a local agent, otherwise profiling may not start. ↓

fix Set environment variable 'BLACKFIRE_AGENT_SOCKET' to the path of the Blackfire agent socket (e.g., '/var/run/blackfire/agent.sock').

Imports

BlackfireProbe
wrong
```
from blackfire_sdk import BlackfireProbe
```
correct
```
from blackfire import BlackfireProbe
```
Wrong package name, the correct import is from 'blackfire' module.
probe
wrong
```
import blackfire.probe as probe
```
correct
```
from blackfire import probe
```
Common mistake: 'probe' is a module, use direct import of the function.
enable
wrong
```
from blackfire.probe import enable
```
correct
```
from blackfire import enable
```
'enable' is a top-level function in the blackfire module.

Quickstart

Basic profiling using BlackfireProbe as a context manager. Replace client ID and token with your Blackfire credentials.

from blackfire import BlackfireProbe, generate_instrumentation

# Set environment variables or config keys
import os
os.environ['BLACKFIRE_CLIENT_ID'] = 'your-client-id'
os.environ['BLACKFIRE_CLIENT_TOKEN'] = 'your-client-token'

# Start profiling a block
with BlackfireProbe() as probe:
    # Your code to profile
    result = sum(range(1000000))
    print(result)