Introducing Blackfire Doctor: the self-diagnosis tool for your setup
Configuring Blackfire can sometimes feel like a puzzle with too many missing pieces. With our new blackfire doctor CLI command, you can validate your installation, fix issues faster, and get back to what matters most: building great applications.
By Thomas di Luccio, on Oct 08, 2025 When setup feels harder than it should
We’ve all been there. You’re excited to try a new tool, you follow the installation steps carefully, but something doesn’t quite click.
In most cases, Blackfire’s custom installation scripts make the setup a no‑brainer. However, in a few edge cases, the agent won’t connect, the probe won’t respond, and you end up refreshing the docs for the tenth time, wondering if it’s you or the tool.
For new Blackfire users, that moment can be especially frustrating. Configuring the Agent, Probe, and system settings sometimes involves details that aren’t obvious at first glance. And while our support team is always here to help, we wanted to make setup validation a whole lot easier.
Enter blackfire doctor
That’s why we built blackfire doctor, a new CLI command designed to eliminate the guesswork from installation and troubleshooting.
Think of it as your personal health check for Blackfire. It runs a complete diagnosis of your setup:
- Agent: verifies the daemon is running and reachable.
- Probe: checks if the PHP or Python probe is correctly loaded.
- Configuration: inspects your environment variables and setup.
- Connectivity: ensures Blackfire can reach our platform endpoints.
Instead of digging through logs or copy-pasting long error messages, you now get a clear, standardized report in seconds.
See blackfire doctor in action
Why it matters
For you as a developer, blackfire doctor is your go‑to tool for self‑diagnosing setup issues:
- Spend less time stuck on installation problems.
- Quickly validate that everything is working as expected.
- Run it anytime to gain confidence before optimizing performance.
And whenever you need more help, you can share the command’s report with our support team. That dump provides them with precise insights into your setup, allowing them to help you fix things faster and more effectively.In short, you stay in control, and when needed, we’re right behind you with actionable guidance.
Running in Docker
Many of you run the Blackfire Agent inside a Docker container while keeping the CLI on your host machine. In that case, you can still use blackfire doctor to validate the setup by pointing it to the Agent’s exposed socket. For example, as the agent is usually available on port 8307:
blackfire doctor --socket=tcp://localhost:8307
This lets you check that your containerized Agent is reachable and configured adequately before moving on.
Call the Doctor, today
If you already have the Blackfire CLI installed, just run:
blackfire doctor
It’s that simple.
👉 Read the full documentation for more details.
We can’t wait to hear what you think. Give blackfire doctor a try, and let us know how it helps you get started faster with Blackfire.
To better observability and beyond
