{"id":23366,"library":"blackfire","title":"Blackfire Python SDK","description":"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.","status":"active","version":"2026.3.0","language":"python","source_language":"en","source_url":"https://github.com/blackfireio/blackfire-python","tags":["profiling","performance","monitoring","blackfire"],"install":[{"cmd":"pip install blackfire","lang":"bash","label":"Install via pip"}],"dependencies":[],"imports":[{"note":"Wrong package name, the correct import is from 'blackfire' module.","wrong":"from blackfire_sdk import BlackfireProbe","symbol":"BlackfireProbe","correct":"from blackfire import BlackfireProbe"},{"note":"Common mistake: 'probe' is a module, use direct import of the function.","wrong":"import blackfire.probe as probe","symbol":"probe","correct":"from blackfire import probe"},{"note":"'enable' is a top-level function in the blackfire module.","wrong":"from blackfire.probe import enable","symbol":"enable","correct":"from blackfire import enable"}],"quickstart":{"code":"from blackfire import BlackfireProbe, generate_instrumentation\n\n# Set environment variables or config keys\nimport os\nos.environ['BLACKFIRE_CLIENT_ID'] = 'your-client-id'\nos.environ['BLACKFIRE_CLIENT_TOKEN'] = 'your-client-token'\n\n# Start profiling a block\nwith BlackfireProbe() as probe:\n    # Your code to profile\n    result = sum(range(1000000))\n    print(result)","lang":"python","description":"Basic profiling using BlackfireProbe as a context manager. Replace client ID and token with your Blackfire credentials."},"warnings":[{"fix":"Upgrade to Python 3.6+ and install blackfire>=2022.0.0.","message":"Blackfire dropped support for Python 2.7 and 3.5 in version 2022.x. Ensure you are using Python 3.6+.","severity":"breaking","affected_versions":"<2022.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Replace 'from blackfire.sdk import ...' with 'from blackfire import ...'.","message":"The 'blackfire.sdk' module is deprecated. All functionality is now in top-level 'blackfire'.","severity":"deprecated","affected_versions":">=2022.0.0"},{"fix":"Set environment variable 'BLACKFIRE_AGENT_SOCKET' to the path of the Blackfire agent socket (e.g., '/var/run/blackfire/agent.sock').","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run 'pip install blackfire' in your environment.","cause":"The blackfire package is not installed in the current Python environment.","error":"ImportError: No module named 'blackfire'"},{"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.","cause":"The Blackfire agent is not running or the socket path is incorrect.","error":"blackfire.exceptions.BlackfireException: Unable to connect to Blackfire agent"},{"fix":"Upgrade to blackfire>=2022.0.0 using 'pip install --upgrade blackfire'. Ensure import is 'from blackfire import BlackfireProbe'.","cause":"Using an older version of blackfire where BlackfireProbe was not available or imported incorrectly.","error":"AttributeError: module 'blackfire' has no attribute 'BlackfireProbe'"},{"fix":"Remove the 'signature' argument. Use the 'name' or 'transaction_name' parameter instead. Check the documentation for the current API.","cause":"The 'signature' parameter was removed in a newer version of the BlackfireProbe.","error":"TypeError: __init__() got an unexpected keyword argument 'signature'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}