1. Documentation
  2. Getting Up and Running
  3. Installing Blackfire

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
on
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).

If you need to install the Blackfire stack manually because every other installation methods failed, please contact us and mention your platform, language type, and language version.

In the meantime, use the following steps for manual installation.

You are strongly advised to use the other installation methods available if possible as they give you seamless upgrade methods.

  1. Download the best binary for your platform (macOS):
  2. Move the downloaded blackfire file to a directory in your path (e.g. /usr/local/bin) and make the file executable.

  1. This command asks for some Blackfire server credentials, log in or sign up now to get them:

    or

    Learn more about the agent configuration file.

  2. You can manually launch the agent each time you want to profile a page or a script by using blackfire agent:start, but it is better to register a service in order to have it launched automatically.

    Please refer to your OS documentation to determine how to register a service (eg. using systemd, init.d, upstart or launchtl.)

  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. Download the best Probe library for your platform (macOS):
  2. Determine your PHP extensions directory: 
    php -i | grep 'extension_dir'

    When using a PHP different than the one shipped with macOS, please ensure the php binary from your PATH is the one you want to use Blackfire on. For example if you are using MAMP on macOS, when you run which php, the path returned should mention MAMP.

    Please also note you may have to edit two php.ini files, one for the web and one for the command line.

    For MAMP Pro users, please note that you should not directly edit the php.ini file used in web mode. Instead you need to edit the template from the MAMP Pro interface.

  3. Move the downloaded blackfire-*.so (blackfire-*.dll for Windows) file to this directory.
  4. Create the Probe configuration file.

    5. On Linux systems, check that the /var/run/blackfire/ directory exists and is accessible by both the Agent and the Probe.
    For macOS users, check that the /usr/local/var/run/ directory exists and is accessible by both the Agent and the Probe.

  5. Restart your web server or PHP-FPM and check that there are no errors in the logs. To debug problems, you can change the log level and the log file in the Probe configuration.

Known incompatibilities

PHP will likely crash when Blackfire is used when one of the following extensions is also enabled: XHProf, Pinba, and Suhosin.

If XDebug is installed, the PHP engine may not behave as expected; consider disabling it when profiling.

If pcov extension is installed, Blackfire will not behave as expected; consider disabling it when profiling.

Enable Monitoring

You can now enable monitoring for your environments.

To profile applications, you need to use 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: