{"id":8205,"library":"grafanalib","title":"Grafanalib","description":"Grafanalib is a Python library for programmatically building Grafana dashboards. It allows users to define dashboards, panels, and targets in Python code, generating the corresponding Grafana JSON model. As of version 0.7.1, it focuses on adding support for newer Grafana features, with releases occurring periodically to keep up with Grafana updates and dependency bumps.","status":"active","version":"0.7.1","language":"en","source_language":"en","source_url":"https://github.com/weaveworks/grafanalib","tags":["grafana","dashboard-as-code","monitoring","observability"],"install":[{"cmd":"pip install grafanalib","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Dashboard","correct":"from grafanalib.core import Dashboard"},{"symbol":"Graph","correct":"from grafanalib.core import Graph"},{"symbol":"TimeSeries","correct":"from grafanalib.core import TimeSeries"},{"note":"GraphiteTarget is a specific implementation of Target; generally, you import the base Target or the specific type you need (e.g., CloudwatchMetricsTarget, InfluxDBTarget).","wrong":"from grafanalib.core import GraphiteTarget","symbol":"Target","correct":"from grafanalib.core import Target"}],"quickstart":{"code":"import json\nfrom grafanalib.core import Dashboard, Graph, Row, OPS_FORMAT, SEC_FORMAT, YAxes, YAxis\n\ndashboard = Dashboard(\n    title=\"My First Grafana Dashboard\",\n    description=\"A simple dashboard created with grafanalib\",\n    rows=[\n        Row(\n            panels=[\n                Graph(\n                    title=\"CPU Usage\",\n                    dataSource='my_prometheus_datasource',\n                    targets=[\n                        {\n                            \"expr\": 'node_cpu_seconds_total{mode=\"idle\"}',\n                            \"legendFormat\": \"idle\",\n                            \"refId\": \"A\"\n                        }\n                    ],\n                    yAxes=YAxes([YAxis(format=OPS_FORMAT), YAxis(format=SEC_FORMAT)]),\n                )\n            ]\n        )\n    ],\n    id=None\n).to_json_data(indent=2)\n\nprint(dashboard)\n\n# To upload this dashboard to Grafana:\n# 1. Save the output to a file (e.g., my_dashboard.json)\n# 2. Use the Grafana UI to import the JSON\n# 3. Alternatively, use grafanalib.client or another script to POST to Grafana API","lang":"python","description":"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."},"warnings":[{"fix":"Ensure 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`.","message":"Grafanalib'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.","severity":"gotcha","affected_versions":"All versions where new features are introduced (e.g., v0.6.0 added Grafana v8 panels)."},{"fix":"After 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`).","message":"Grafanalib generates JSON; it does not deploy to Grafana automatically. Users often expect direct integration or automatic upload.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Consider 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.","message":"Hardcoding datasource names can limit dashboard portability. If datasource names change across different Grafana environments (e.g., dev vs. prod), dashboards might break.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify 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.","cause":"When attempting to upload a dashboard via Grafana API, the provided API key is invalid or lacks sufficient permissions.","error":"HTTP Error 401: Unauthorized"},{"fix":"Upgrade 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`.","cause":"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.","error":"Dashboard import failed: Failed to save dashboard: Invalid JSON: panels[0]: invalid panel type"},{"fix":"Use 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.","cause":"Incorrect import pattern. You might be trying to access `grafanalib.core.Dashboard` after `import grafanalib` instead of importing `Dashboard` directly.","error":"AttributeError: module 'grafanalib' has no attribute 'core'"}]}