Python Visuals in Power BI (PBIR)

Use pbir for every report mutation. Read PBIR metadata only for diagnosis. If pbir is unavailable or lacks an operation, stop and report the gap; never edit report JSON directly.

Python visuals execute matplotlib/seaborn scripts to render static PNG images on the Power BI canvas. Prefer seaborn over raw matplotlib for cleaner syntax and better defaults -- it handles most chart types with less code.

Visual Identity

• visualType: pythonVisual
• Data role: Values (columns and measures, multiple allowed)
• Data variable: dataset (pandas DataFrame, auto-injected)
• Row limit: 150,000 rows
• Output: Static PNG at 72 DPI -- no interactivity

Workflow: Creating a Python Visual

Step 1: Add the Visual

pbir add visual pythonVisual "Report.Report/Page.Page" --name PythonChart \
  --data "Values:Sales.Date" --data "Values:Sales.Revenue"

Step 2: Write the Script

import matplotlib.pyplot as plt

fig, ax = plt.subplots(figsize=(8, 4))
ax.bar(dataset["Date"], dataset["Sales"], color="#5B8DBE")
ax.spines["top"].set_visible(False)
ax.spines["right"].set_visible(False)
plt.tight_layout()
plt.show()  # MANDATORY

Critical rules:

• plt.show() is mandatory as the final line -- nothing renders without it
• dataset is auto-injected as a pandas DataFrame; do not create it
• Column names match the nativeQueryRef (display name) from field bindings
• Only the last plt.show() call renders; multiple figures not supported

Step 2b: Review

Before presenting the script to the user, dispatch the python-reviewer agent to validate correctness and provide design feedback.

Step 3: Inject the Script

pbir visuals python "Report.Report/Page.Page/PythonChart.Visual" \
  --script-file chart.py

The CLI handles PBIR string escaping.

Step 4: Validate