Installing Blackfire

Installing and updating Blackfire should be a quick process. This document will guide you through the steps.

For a better experience, you should or .

Tell us what you want to do:

I want to Blackfire
which uses
for the language.

The v2 version is the one you want to use. If you have automation based on the previous version, select v1, which is still supported until the Aug, 31th 2021.

If you are upgrading from v1, please read the upgrade guide.

To start using Blackfire, we are going to install the following:

  • A language extension;
  • An agent to communicate with Blackfire's servers;
  • A profiling client (a browser extension or a CLI tool).

Blackfire uses a custom Debian repository to distribute its packages; it is compatible with most Debian-based distributions like Ubuntu and Linux-Mint.

  1. Register the packagecloud key:
    wget -q -O - | sudo dd of=/usr/share/keyrings/blackfire-archive-keyring.asc
  2. Add the repository to Debian source list:
    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/blackfire-archive-keyring.asc] any main" | sudo tee /etc/apt/sources.list.d/blackfire.list
  3. Update the repositories:
    sudo apt update
  1. Install the blackfire package:
    sudo apt install blackfire
  1. This command asks for some Blackfire server credentials, log in or sign up now to get them:


    Learn more about the agent configuration file.
  2. Restart the agent service:
    sudo systemctl restart blackfire-agent

    During the agent installation, a new blackfire-agent service was created to start, stop, and restart it. Whenever you modify the agent configuration, restart it.

  3. If something goes wrong, check out the log file generated by default in /var/log/blackfire/agent.log. Change the log file or the log level in the agent configuration file.
  1. Install pip:
    sudo apt install python-pip
  2. Install the blackfire package:
    pip install blackfire --user

    If you have multiple versions of Python installed on your system, it is possible that you have multiple versions of the pip binary installed as well. For example, you can have pip2 installed for Python >= 2.0, and pip3 installed for Python >= 3.0.

  3. Ensure blackfire-python command is in your $PATH.
    Blackfire pip package installs the blackfire-python command, which can be used for zero configuration profiling.

    The folder where blackfire-python is installed may vary depending on your Python environment (e.g. pyenv, virtualenv).
    Note that the folder blackfire-python is installed in must be in your $PATH.

    If you previously installed Blackfire bootstrap configuration hook (blackfire_bootstrap.pth, in versions <= 1.4.5), you must uninstall it by running the following command:

    python -m blackfire uninstall-bootstrap

Enable Monitoring

You can now enable monitoring for your environments.

To profile applications, use the Python SDK.

For on-demand profiling, you need to install a profiling client:

  • Profile from a browser via our browser extensions (Web applications only).

  • Profile from the command line via the blackfire tool (Web applications, APIs, command line tools, daemons, and more).

    Configure it with your personal credentials:

    blackfire client:config --client-id=CLIENT_ID --client-token=CLIENT_TOKEN

Start profiling via: