Developer · Guide
How to Profile WordPress With Xdebug

Short answer
To profile WordPress with Xdebug, set xdebug.mode to profile in php.ini, set xdebug.start_with_request to trigger, and load one page with the XDEBUG_PROFILE trigger. Xdebug writes a cachegrind.out snapshot to the folder set by xdebug.output_dir. Open that file in PhpStorm, KCachegrind, or QCacheGrind to see which functions use the most time and memory, and profile on a local or staging copy, never on a live site.
Key takeaways
- Set xdebug.mode to profile in php.ini to turn on the profiler in Xdebug 3.
- Use xdebug.start_with_request set to trigger so profiling runs only on requests you choose.
- Snapshots are cachegrind.out files in the folder set by xdebug.output_dir, which defaults to /tmp.
- Open snapshots in PhpStorm, KCachegrind on Linux, or QCacheGrind on macOS and Windows.
- Sort by Own time to find the functions that are slow on their own.
- Profile on a local or staging copy, never on a live production server.
What does Xdebug profiling do for WordPress?
Profiling with Xdebug shows how the PHP behind each WordPress page load uses execution time and memory.
WordPress runs on PHP, so Xdebug profiles the PHP behind each WordPress page load. JetBrains PhpStorm docs state that PhpStorm shows profiling snapshots generated by Xdebug to examine how a PHP application uses execution time and memory (checked November 2026).
Use profiling when a page feels slow and you need to know which function costs the most time. Do not guess at the slow part. A snapshot gives you numbers for each function instead of a hunch.
Profiling is not the same as turning on WordPress debug logging. Debug logging records errors and warnings in a log file. Profiling records how long each function runs and how much memory it uses.
WordPress.org states that WP_DEBUG_LOG saves errors to a debug.log file, and that WP_DEBUG is meant for local testing and staging installs, not live sites (checked November 2026). Profiling and debug logging are separate tools, so use each one for its own job.
What do you need before you start profiling?
You need Xdebug installed for the PHP that runs WordPress, plus a local or staging copy of the site.
Xdebug documentation states that xdebug.mode controls which features are enabled and can only be set in php.ini or files like 99-xdebug.ini read at PHP start (checked November 2026). Check that Xdebug is present for the PHP version your site uses before you change any setting.
Profile on a local or staging copy, never live. Profiling is resource-heavy and slows PHP execution, so do not run it on a production server.
If you have not tried basic speed steps yet, start with the guide on how to speed up WordPress before you profile.
Set aside 30 to 60 minutes for your first profile run. Most of that time goes to setup and reading the first snapshot, not to loading the page.
How do you enable profiling in Xdebug 3?
Set xdebug.mode to profile in php.ini to turn on the profiler in Xdebug 3.
Xdebug documentation states that “profile” enables profiling to analyse performance bottlenecks with tools like KCachegrind (checked November 2026). Add this line to php.ini or to a file like 99-xdebug.ini:
xdebug.mode=profile
xdebug.start_with_request=trigger
xdebug.output_dir=/tmp
JetBrains PhpStorm docs state that in Xdebug 3 you set xdebug.mode = profile to enable the profiler, while Xdebug 2 used xdebug.profiler_enable = 1 (checked November 2026). Use the Xdebug 3 setting if your PHP setup runs Xdebug 3.
You can combine more than one mode with commas. Xdebug documentation states that multiple modes can be combined with commas, for example xdebug.mode=develop,trace (checked November 2026). Keep the list short while you profile, so the snapshot stays focused on time and memory.
How do you trigger a profile only when you want one?
Set xdebug.start_with_request to trigger so profiling runs only when you send the trigger value.
JetBrains PhpStorm docs state that to trigger from the browser, you set xdebug.mode = profile plus xdebug.start_with_request = trigger, then use the XDEBUG_PROFILE cookie or the ?XDEBUG_PROFILE=1 URL parameter (checked November 2026). That pair stops Xdebug from profiling every page load.
With the default start_with_request value for profile mode, the profiler starts for every request. Xdebug documentation states that with start_with_request set to trigger, you enable the profiler with an environment value, a GET or POST parameter, or a cookie named XDEBUG_TRIGGER (checked November 2026).
You can restrict the trigger to one exact value. Xdebug documentation states that xdebug.trigger_value controls which specific trigger value will activate the trigger, and it shows StartProfileForMe as an example value (checked November 2026). Use a value only you know, and do not share it in a public link.
Where do profiling snapshots go and how are they named?
Set xdebug.output_dir to pick the folder for snapshots, and keep each file name starting with cachegrind.out.
Xdebug documentation states that xdebug.output_dir defaults to /tmp and is where Xdebug writes tracing, profiling and garbage collection statistics, and that the directory must be writable by the user PHP runs as (checked November 2026). Pick a folder you can open easily, and check that PHP can write to it.
JetBrains PhpStorm docs state that xdebug.output_dir in Xdebug 3, or xdebug.profiler_output_dir in Xdebug 2, sets where snapshots are stored, and that xdebug.profiler_output_name sets the file name, with a default of cachegrind.out.%p where %p is the process ID (checked November 2026).
The file name should always start with cachegrind.out.
| Setting | Xdebug 3 | Xdebug 2 |
|---|---|---|
| Enable profiling | xdebug.mode=profile | xdebug.profiler_enable=1 |
| Output folder | xdebug.output_dir | xdebug.profiler_output_dir |
| File name | xdebug.profiler_output_name | xdebug.profiler_output_name |
| Default file name | cachegrind.out.%p | cachegrind.out.%p |
| Default folder | /tmp | /tmp |
Xdebug documentation states that the profiler writes profiling information into the directory set by xdebug.output_dir, and that the file name always starts with cachegrind.out (checked November 2026). Look for a new file with that prefix right after the request you trigger.
How do you profile a WordPress page from the browser?
Load the WordPress page in your browser with the XDEBUG_PROFILE trigger to make one snapshot for that request.
Follow these steps in order:
- Set xdebug.mode to profile and xdebug.start_with_request to trigger in php.ini.
- Set xdebug.output_dir to a folder PHP can write to.
- Save the file and load your local or staging site in the browser.
- Add ?XDEBUG_PROFILE=1 to the end of the page URL, or set the XDEBUG_PROFILE cookie.
- Load the page once, then check the output folder for a new cachegrind.out file.
- Open that file in PhpStorm or in KCachegrind to read the result.
WordPress debug logging is a separate tool. Use wp-config.php constants only for WordPress debug logging, and do not claim Xdebug reads that log.
A guide on how to enable debug mode in WordPress explains those debug constants.
A guide on how to read the WordPress debug log shows how to read the log file that debug mode writes.
Profile one page at a time at first. A home page, a slow post page, and a slow admin page each give a different snapshot, and comparing them shows which page has the real cost.
How do you profile WordPress from the command line?
Run PHP on the command line with profile mode flags to make a snapshot for one script without changing php.ini.
JetBrains PhpStorm docs state that you can run PHP with -dxdebug.mode=profile -dxdebug.start_with_request=yes -dxdebug.output_dir=folder -dxdebug.profiler_output_name=cachegrind.out.%p to generate a snapshot for a CLI script without changing php.ini (checked November 2026).
Use this form when you want to profile a script, a cron job, or a WP-CLI style task.
Here is the command shape, with folder replaced by your own output folder:
php -dxdebug.mode=profile -dxdebug.start_with_request=yes -dxdebug.output_dir=/tmp/profiles -dxdebug.profiler_output_name=cachegrind.out.%p script.php
Xdebug documentation states that the XDEBUG_MODE environment variable takes precedence over xdebug.mode on the command line (checked November 2026). If a snapshot does not appear, check whether that variable is set in your shell and is overriding your flag.
Use start_with_request=yes on the command line when you want the whole script profiled. Use trigger on the command line only when you also pass the trigger value for that run.
How do you read a profiling snapshot in PhpStorm?
Open the cachegrind.out file in PhpStorm to see Execution Statistics, the Call Tree, Callees, and Callers.
JetBrains PhpStorm docs state that PhpStorm shows profiling snapshots with four analysis views: Execution Statistics, Call Tree, Callees, and Callers (checked November 2026). Start with Execution Statistics, since it gives a summary for each function.
JetBrains PhpStorm docs state that the metrics are Time, the percent of time in the function plus everything it calls, Own time, the percent in the function alone, Memory in bytes, Own memory, and Calls, the number of times the function was called (checked November 2026).
Sort by Own time first to find functions that are slow on their own.
PHP Manual states that memory_get_usage returns the amount of memory, in bytes, that is currently allocated to the PHP script (checked November 2026). A snapshot shows memory per function, while this function reports the total for the running script.
Call Tree shows the execution paths that led to each function. Callees shows what a function called, and Callers shows what called it. Use those two views to trace a slow function back to the WordPress code that started it.
You can open more than one snapshot at once. JetBrains PhpStorm docs state that several snapshots can be opened at once and PhpStorm aggregates them into an averaged result (checked November 2026). That average is useful when one page load varies from the next.
How do you read a snapshot in KCachegrind or QCacheGrind?
Open cachegrind.out files in KCachegrind on Linux or QCacheGrind on macOS and Windows.
Xdebug documentation states that KCachegrind is the analysis tool for profiling (checked November 2026). Xdebug documentation states that the profiler outputs a Cachegrind compatible file, and that you can open it with KCachegrind on Linux or QCacheGrind on Windows and macOS (checked November 2026).
Open the file from the viewer, not from a text editor. A cachegrind.out file is a data file, so a text editor shows raw lines that are hard to read.
Look for the same signals as in PhpStorm: the functions with the highest own time, the highest call counts, and the largest memory use. Those three signals point to the code that costs the most on that page load.
Save a copy of a snapshot before you change any code. That copy lets you compare the before and after numbers after you fix the slow part.
How do you check that profiling worked?
Check that a new cachegrind.out file appears in your output folder right after the request you triggered.
A new file with a fresh time stamp means the trigger worked. Open it and check that it lists functions from your WordPress page load, not an empty result.
If no file appears, check three settings in order. First, confirm xdebug.mode is profile.
Second, confirm start_with_request is trigger and that you sent XDEBUG_PROFILE. Third, confirm xdebug.output_dir exists and PHP can write to it.
If PHP reports an error instead, the guide on how to check PHP error logs shows where to look.
A slow page can also come from an old PHP version. See the guide on does PHP version affect WordPress speed for that check.
Caching of compiled PHP is a separate topic from profiling. See the guide on what is PHP OPcache to learn how that cache works.
What mistakes should you avoid?
Never profile on a live production server, and never leave profiling on for every request.
Profiling is resource-heavy and slows PHP execution. Profile on a local or staging copy, never live, and turn the trigger back to off when you finish.
Do not use the default start_with_request value on a busy site. With the default, the profiler starts for every request, and that fills your output folder fast. Use trigger mode, and send the trigger only for the page you want to measure.
Do not read a cachegrind.out file as plain text and guess at the numbers. Open it in PhpStorm, KCachegrind, or QCacheGrind, where the time, own time, memory, and call counts are shown per function.
Do not mix up profiling with debug logging. Xdebug profiling measures time and memory per function. WordPress debug logging records errors in a log file, and wp-config.php constants control that log, not Xdebug.
Do not leave old snapshots in the output folder for weeks. Delete snapshots you no longer need, so a fresh file is easy to spot after your next triggered request.
Frequently asked questions
Do I need PhpStorm to profile WordPress with Xdebug?
No. PhpStorm is one viewer for the snapshots, but you can open cachegrind.out files in KCachegrind on Linux or QCacheGrind on macOS and Windows. Xdebug creates the snapshot, and any of these tools can read it. Pick the viewer you already have installed, and use the same file either way.
What is the difference between Xdebug 2 and Xdebug 3 profiling settings?
In Xdebug 3, set xdebug.mode to profile to turn on the profiler. In Xdebug 2, the setting was xdebug.profiler_enable set to 1. The output folder setting also changed names: Xdebug 3 uses xdebug.output_dir, while Xdebug 2 used xdebug.profiler_output_dir. The file name setting, xdebug.profiler_output_name, is the same in both versions.
Why is there no cachegrind file after I load a page?
Check three settings in order. First, confirm xdebug.mode is profile. Second, confirm start_with_request is trigger and that you sent the XDEBUG_PROFILE trigger with the request. Third, confirm xdebug.output_dir exists and that the user PHP runs as can write to it. The default folder is /tmp, so check there first.
Can I profile WordPress on my live site?
No. Profiling is resource-heavy and slows PHP execution, so do not run it on a production server. Copy the site to a local or staging setup and profile there instead. That copy gives the same function-level numbers without slowing the live site for visitors.
How do I profile only one WordPress page?
Set xdebug.start_with_request to trigger, then add ?XDEBUG_PROFILE=1 to the page URL or set the XDEBUG_PROFILE cookie before you load the page. Xdebug then profiles only that request. You can also restrict the trigger to one exact value with xdebug.trigger_value, for example StartProfileForMe.
Sources
- Profiling with Xdebug JetBrains
- Xdebug Documentation: Settings Reference Xdebug
- Profiling Xdebug
- Debugging in WordPress WordPress.org
- memory_get_usage PHP Manual
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.


