Install & Compatibility
Where this runs
tested against v0.7.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.348s · 18.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.288s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Dashboard
✓ from grafanalib.core import Dashboard
Graph
✓ from grafanalib.core import Graph
TimeSeries
✓ from grafanalib.core import TimeSeries
Target
✓ from grafanalib.core import Target
✗ from grafanalib.core import GraphiteTarget
GraphiteTarget is a specific implementation of Target; generally, you import the base Target or the specific type you need (e.g., CloudwatchMetricsTarget, InfluxDBTarget).
This quickstart demonstrates how to create a basic Grafana dashboard with a single row and a CPU Usage graph panel. It uses a Prometheus datasource (replace 'my_prometheus_datasource' with your actual datasource name). The output is a JSON string which can be saved and imported into Grafana.
import json
from grafanalib.core import Dashboard, Graph, Row, OPS_FORMAT, SEC_FORMAT, YAxes, YAxis
dashboard = Dashboard(
title="My First Grafana Dashboard",
description="A simple dashboard created with grafanalib",
rows=[
Row(
panels=[
Graph(
title="CPU Usage",
dataSource='my_prometheus_datasource',
targets=[
{
"expr": 'node_cpu_seconds_total{mode="idle"}',
"legendFormat": "idle",
"refId": "A"
}
],
yAxes=YAxes([YAxis(format=OPS_FORMAT), YAxis(format=SEC_FORMAT)]),
)
]
)
],
id=None
).to_json_data(indent=2)
print(dashboard)
# To upload this dashboard to Grafana:
# 1. Save the output to a file (e.g., my_dashboard.json)
# 2. Use the Grafana UI to import the JSON
# 3. Alternatively, use grafanalib.client or another script to POST to Grafana API
Debug
Known issues
gotchaGrafanalib's generated JSON model compatibility with Grafana server versions: Features like the `TimeSeries` panel (introduced in Grafana v8) will only render correctly if your Grafana instance is compatible (v8+). Deploying a dashboard with newer panel types to an older Grafana server will result in import errors or panels failing to render.fixEnsure your Grafana server version supports the panel types and features used in your `grafanalib` code. Consult Grafana's release notes and `grafanalib`'s changelog for specific feature-version mappings. For older Grafana versions, stick to more established panel types like `Graph`.
affects: All versions where new features are introduced (e.g., v0.6.0 added Grafana v8 panels).
gotchaGrafanalib generates JSON; it does not deploy to Grafana automatically. Users often expect direct integration or automatic upload.fixAfter generating the JSON using `dashboard.to_json_data()`, you must manually import it via the Grafana UI, use the `grafanalib.client` module (which requires a Grafana API key and URL), or write a custom script to POST the JSON to the Grafana API endpoint (`/api/dashboards/db`).
affects: All versions.
gotchaHardcoding datasource names can limit dashboard portability. If datasource names change across different Grafana environments (e.g., dev vs. prod), dashboards might break.fixConsider using Grafana's templating features (e.g., `Template.datasource`) or environment variables to dynamically provide datasource names, making your dashboards more flexible and reusable across environments.
affects: All versions.
Errors
Common errors & fixes
HTTP Error 401: Unauthorized
When attempting to upload a dashboard via Grafana API, the provided API key is invalid or lacks sufficient permissions.
fixVerify that your Grafana API key has 'Editor' or 'Admin' permissions and is correctly configured in your upload script or `grafanalib.client` call. Ensure the API key is not expired.
Dashboard import failed: Failed to save dashboard: Invalid JSON: panels[0]: invalid panel type
You are trying to import a dashboard containing a panel type (e.g., `TimeSeries`, `StateTimeline`, `Pie Chart v2`) that is not supported by your current Grafana server version.
fixUpgrade your Grafana server to a version that supports the specific panel type (e.g., Grafana 8+ for `TimeSeries`). Alternatively, modify your `grafanalib` code to use older, more universally supported panel types like `Graph`.
AttributeError: module 'grafanalib' has no attribute 'core'
Incorrect import pattern. You might be trying to access `grafanalib.core.Dashboard` after `import grafanalib` instead of importing `Dashboard` directly.
fixUse explicit imports: `from grafanalib.core import Dashboard, Graph` etc. Then, refer to `Dashboard()` directly. If you must `import grafanalib`, then you would use `grafanalib.core.Dashboard()` but this is not the idiomatic way.
Upgrade
Version history
0.7.1latest on PyPI · released Jan 12, 2024
Audit
Dependencies
No dependency data recorded yet.