python · pablogsal · Mar 30, 2026 · Mar 8, 2026 · Mar 10, 2026 · Mar 26, 2026
@@ -1003,6 +1003,47 @@ at the top indicate functions that consume significant time either directly
 or through their callees.
 
 
+Differential flame graphs
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Differential flame graphs compare two profiling runs to highlight where
+performance changed. This helps identify regressions introduced by code changes
+and validate that optimizations achieved their intended effect::
+
+   # Capture baseline profile
+   python -m profiling.sampling run --binary -o baseline.bin script.py
+
+   # After modifying code, generate differential flamegraph
+   python -m profiling.sampling run --diff-flamegraph baseline.bin -o diff.html script.py
+
+The visualization draws the current profile with frame widths showing current
+time consumption, then applies color to indicate how each function changed
+relative to the baseline.
+
+**Color coding**:
+
+- **Red**: Functions consuming more time (regressions). Lighter shades indicate
+  modest increases, while darker shades show severe regressions.
+
+- **Blue**: Functions consuming less time (improvements). Lighter shades for
+  modest reductions, darker shades for significant speedups.
+
+- **Gray**: Minimal or no change.
+
+- **Purple**: New functions not present in the baseline.
+
+Frame colors indicate changes in **direct time** (time when the function was at
+the top of the stack, actively executing), not cumulative time including callees.
+Hovering over a frame shows comparison details including baseline time, current
+time, and the percentage change.
+
+Some call paths may disappear entirely between profiles. These are called
+**elided stacks** and occur when optimizations eliminate code paths or certain
+branches stop executing. If elided stacks are present, an elided toggle appears
+allowing you to switch between the main differential view and an elided-only
+view that shows just the removed paths (colored purple).
+
+
 Gecko format
 ------------
 
@@ -1488,6 +1529,10 @@ Output options
 
    Generate self-contained HTML flame graph.
 
+.. option:: --diff-flamegraph <baseline.bin>
+
+   Generate differential flamegraph comparing to a baseline binary profile.
+
 .. option:: --gecko
 
    Generate Gecko JSON format for Firefox Profiler.

@@ -5,6 +5,46 @@
    This file extends the shared foundation with flamegraph-specific styles.
    ========================================================================== */
 
+/* --------------------------------------------------------------------------
+   Differential Flamegraph
+   -------------------------------------------------------------------------- */
+
+:root {
+  /* Regression colors */
+  --diff-regression-deep: #d32f2f;
+  --diff-regression-medium: #e57373;
+  --diff-regression-light: #ef9a9a;
+  --diff-regression-verylight: #ffcdd2;
+
+  /* Improvement colors */
+  --diff-improvement-deep: #1976d2;
+  --diff-improvement-medium: #42a5f5;
+  --diff-improvement-light: #64b5f6;
+  --diff-improvement-verylight: #90caf9;
+
+  /* Other differential colors */
+  --diff-neutral: #bdbdbd;
+  --diff-new: #9575cd;
+  --diff-elided: #b39ddb;
+}
+
+/* Dark mode differential colors - adjusted for contrast against dark backgrounds */
+[data-theme="dark"] {
+  --diff-regression-deep: #ef5350;
+  --diff-regression-medium: #e57373;
+  --diff-regression-light: #ef9a9a;
+  --diff-regression-verylight: #ffcdd2;
+
+  --diff-improvement-deep: #42a5f5;
+  --diff-improvement-medium: #64b5f6;
+  --diff-improvement-light: #90caf9;
+  --diff-improvement-verylight: #bbdefb;
+
+  --diff-neutral: #757575;
+  --diff-new: #b39ddb;
+  --diff-elided: #ce93d8;
+}
+
 /* --------------------------------------------------------------------------
    Layout Overrides (Flamegraph-specific)
    -------------------------------------------------------------------------- */
@@ -277,7 +317,9 @@ body.resizing-sidebar {
 /* View Mode Section */
 .view-mode-section .section-content {
   display: flex;
-  justify-content: center;
+  flex-direction: column;
+  gap: 10px;
+  align-items: center;
 }
 
 /* Collapsible sections */
@@ -815,6 +857,41 @@ body.resizing-sidebar {
   color: var(--accent);
 }
 
+.tooltip-diff {
+  margin-top: 12px;
+  padding-top: 12px;
+  border-top: 1px solid var(--border);
+}
+
+.tooltip-diff-title {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--accent);
+  margin-bottom: 8px;
+}
+
+.tooltip-diff-row {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 4px 14px;
+  font-size: 12px;
+  margin-bottom: 4px;
+}
+
+.tooltip-diff-row.regression .tooltip-stat-value {
+  color: var(--diff-regression-deep);
+  font-weight: 700;
+}
+
+.tooltip-diff-row.improvement .tooltip-stat-value {
+  color: var(--diff-improvement-deep);
+  font-weight: 700;
+}
+
+.tooltip-diff-row.neutral .tooltip-stat-value {
+  color: var(--text-secondary);
+}
+
 .tooltip-source {
   margin-top: 10px;
   padding-top: 10px;
@@ -989,7 +1066,8 @@ body.resizing-sidebar {
    Flamegraph-Specific Toggle Override
    -------------------------------------------------------------------------- */
 
-#toggle-invert .toggle-track.on {
+#toggle-invert .toggle-track.on,
+#toggle-elided .toggle-track.on {
   background: #8e44ad;
   border-color: #8e44ad;
   box-shadow: 0 0 8px rgba(142, 68, 173, 0.3);