# Graphite-Web: the Django renderer and dashboard layer for a Graphite metrics stack > Graphite-Web is the web application that renders graphs and dashboards on top of Carbon and Whisper. It is a component, not a standalone monitoring product, and the install reflects that. **graphite-project/graphite-web** — A highly scalable real-time graphing system - Repository: https://github.com/graphite-project/graphite-web - Website: http://graphite.readthedocs.org/ - Stars: 6,123 · Forks: 1,255 - Language: JavaScript - License: Apache-2.0 - Published: 2026-09-22 · Updated: 2026-09-22 · Language: en - Canonical page: https://hysenlabs.com/projects/graphite-project-graphite-web ## What Graphite-Web actually is inside the Graphite stack The README describes Graphite as three major components: Graphite-Web, a Django-based web application that renders graphs and dashboards; the Carbon metric processing daemons; and the Whisper time-series database library. That framing matters more than any feature list. Graphite-Web is the presentation and query layer of a larger system, and the repository is the webapp directory plus packaging, configuration and documentation around it. The audience is therefore narrow and specific. You are running Carbon to receive metrics and Whisper to store them, and you want the HTTP surface that turns those stored series into images and dashboard pages. If you are looking for something that collects metrics by itself, this is not that component. The project's own component diagram is the clearest statement of scope: the webapp sits alongside the daemons and the storage library rather than above them as a product. One consequence of being one component of three is that version compatibility is a shared concern. The requirements file pulls Whisper directly from its repository rather than from a pinned package release, so the webapp and the storage library are expected to move together. That is a real coupling, not a packaging accident. ## How requests flow from a metric name to a rendered graph The architecture visible in the repository is a Django project under webapp/, configured through graphite.settings. Requests arrive at the web application, which resolves a target expression against stored series and renders the result. The README does not document the query language or the render API in detail; it points to readthedocs for installation, configuration and usage, and that is where the target syntax and the render endpoints are described. What the repository does show is how the application is wired at runtime. Settings come from graphite.settings, storage and configuration locations are controlled by environment variables, and the database is managed through Django's migration machinery. The requirements file names python-memcached, django-tagging, cairocffi, gunicorn and whitenoise among the dependencies, which tells you the shape of the deployment: a WSGI application served by gunicorn, with Cairo doing the drawing and memcached available as a cache. Cairo is worth calling out as a constraint rather than a detail. cairocffi requires the native Cairo library, and the requirements file's own development notes install libcairo2-dev on Ubuntu or cairo on macOS before pip runs. A headless server without those system packages will fail before any Python code executes. That is a deployment requirement that the Python dependency list alone does not convey. The storage directories in setup.py (whisper, ceres, rrd, log, log/webapp) also reveal the intended layout: the web application expects to sit next to storage that another process writes to. Ceres appears as an optional alternative to Whisper, and RRD support is still present in the directory structure. ## Installing Graphite-Web from a checkout and starting the development server The README defers to readthedocs for installation, so the concrete commands below come from the requirements file's development notes and from setup.py. They assume a Unix-like system with Python available and a virtualenv at .venv. First install the system library that Cairo binding needs, then the Python dependencies. The requirements file gives apt-get install libcairo2-dev on Ubuntu and brew install cairo on macOS. ```bash sudo apt-get install libcairo2-dev pip install -r requirements.txt ``` The next step prepares the directories the application and Carbon expect, and copies the graph template configuration into place: ```bash mkdir -p .venv/storage/ceres .venv/storage/log/carbon-cache .venv/conf touch .venv/conf/carbon.conf .venv/conf/storage-schemas.conf cp conf/graphTemplates.conf.example .venv/conf/graphTemplates.conf export GRAPHITE_ROOT=`pwd` GRAPHITE_STORAGE_DIR=`pwd`/.venv/storage/ GRAPHITE_CONF_DIR=`pwd`/.venv/conf/ ``` Carbon is a separate repository. The requirements notes clone it next to the webapp and start the cache daemon, which is what actually receives metrics: ```bash git clone https://github.com/graphite-project/carbon.git ../carbon ../carbon/bin/carbon-cache.py start ../carbon/bin/carbon-cache.py status ``` Finally initialize the Django database and run the development server. The migrate command takes --run-syncdb and points at graphite.settings with pythonpath=webapp: ```bash mkdir -p .venv/storage/log/webapp /opt/graphite .venv/bin/django-admin.py migrate --run-syncdb --settings=graphite.settings --pythonpath=webapp bin/run-graphite-devel-server.py ./ ``` The requirements notes give an alternative production-shaped command, gunicorn_django bound to 127.0.0.1:8080 from inside webapp/graphite. Note the mkdir on /opt/graphite in the step above: the default install prefix is /opt/graphite, and the notes chown that directory to the current user. If you want a virtualenv-local layout instead, setup.py unsets the prefix when the GRAPHITE_NO_PREFIX environment variable is present. ## Where Graphite-Web stops being the right tool The clearest limitation is structural: Graphite-Web has nothing to graph until something writes metrics into Whisper or Ceres. Installing the webapp alone produces a running Django application with an empty storage tree. Teams that evaluate it as a single package and expect a working dashboard at the end of the install will be surprised, and the README's three-component framing is the warning. The second limitation is the dependency on native Cairo through cairocffi. Graph rendering happens in-process, so the host needs the Cairo library and its development headers. That rules out some minimal container images and adds a build step that pure-Python graphing libraries avoid. The repository's own install notes treat this as a prerequisite step rather than an optional extra. The third is the release cadence visible in the release list. The stable line sat at 1.1.10 from 2022-05-22, with 1.2.1-pre1 on 2025-08-31 and 1.2.1-pre2 on 2026-03-17. The pre-release naming means the newer line is still labelled pre-release. Anyone planning an upgrade should read the CHANGELOG rather than assume the pre-release tag is a drop-in replacement for the stable series. Finally, the dependency range Django>=4.2,<6 is a moving target. A deployment pinned to an older Django cannot install from this requirements file unchanged, and the README does not document a supported older combination. ## Graphite-Web against Prometheus and Grafana The comparison people reach for is Graphite versus Prometheus, and the difference is in the storage and query model rather than in the drawing code. Graphite-Web queries series that Carbon has written into Whisper files on local disk. Prometheus scrapes targets on an interval and stores samples in its own time-series database, with a query language and alerting rules built into the server. With Graphite, ingestion is a separate daemon that receives pushed metrics; with Prometheus, the server pulls them. Grafana is the other frequent comparison, and it is a different kind of thing. Grafana is a dashboard and visualization front end that can read from many backends, including Graphite. Graphite-Web ships its own renderer and dashboard pages rather than acting as a client for other data sources. If your goal is one pane of glass over several backends, Graphite-Web is not that; if your goal is the rendering layer that belongs to a Graphite deployment, it is exactly that. Neither comparison makes one option correct. The choice follows from whether you already push metrics into Carbon and want the matching web layer, or whether you are starting fresh and prefer a pull-based server with storage and alerting in one process. ## Licence, packaging and the cost of keeping up Graphite-Web is licensed under version 2.0 of the Apache License, and the README points to the LICENSE file for details. Apache-2.0 is a permissive licence with an explicit patent grant, which is generally straightforward for commercial deployment, but the LICENSE file is the authority and this is not legal advice. The upgrade cost is dominated by two things visible in the repository. The first is the Django version range. Because requirements.txt asks for Django>=4.2,<6, a Django major-version bump inside that range can change settings behaviour and URL handling, and the migration step is part of every install. The second is the Whisper dependency, which is pulled from a git URL rather than a released version. That means an install of Graphite-Web can pick up a newer Whisper than the one you tested against, and the two are expected to stay in step. Operationally, the environment variables GRAPHITE_ROOT, GRAPHITE_STORAGE_DIR and GRAPHITE_CONF_DIR define where the application looks for configuration and storage, and setup.py's prefix logic defaults the install to /opt/graphite unless GRAPHITE_NO_PREFIX is set. Any upgrade plan has to account for which of those two layouts the deployment uses, because they place configuration files in different directories. ## Conclusion Adopt Graphite-Web if you already run or plan to run Carbon and Whisper and want the graph rendering and dashboard layer that belongs to them. Do not adopt it as a self-contained monitoring system: the README lists three components and Graphite-Web is only one, so without Carbon ingesting metrics and Whisper storing them there is nothing to render. Before installing, verify which Django version your Python environment can satisfy, since requirements.txt asks for Django>=4.2,<6, and confirm whether GRAPHITE_NO_PREFIX is the right choice for your layout, because the default prefix is /opt/graphite. ## FAQ ### What is Graphite-Web used for? It is the Django-based web application in the Graphite stack that renders graphs and dashboards from metrics stored by the other components. The README lists it alongside the Carbon metric processing daemons and the Whisper time-series database library. ### How do I install Graphite-Web from source? The requirements file's development notes install libcairo2-dev, run pip install -r requirements.txt, create the storage and conf directories, export GRAPHITE_ROOT, GRAPHITE_STORAGE_DIR and GRAPHITE_CONF_DIR, then run django-admin.py migrate with --settings=graphite.settings and --pythonpath=webapp. The README itself points to readthedocs for installation instructions. ### Does Graphite-Web store metrics by itself? No. The README describes Graphite as three components, and Graphite-Web is only the web application that renders graphs and dashboards. Metrics are processed by Carbon and stored by Whisper or the optional Ceres library. ### Which port does the Graphite-Web development server use? The requirements file's notes give a gunicorn_django command bound to 127.0.0.1:8080, run from inside webapp/graphite. The repository also provides bin/run-graphite-devel-server.py for local development, whose port the README does not state. ### What licence is Graphite-Web released under? The README states that Graphite-Web is licensed under version 2.0 of the Apache License, with details in the LICENSE file. ## Sources - [graphite-project/graphite-web on GitHub](https://github.com/graphite-project/graphite-web) - [License: Apache-2.0](https://github.com/graphite-project/graphite-web/blob/master/LICENSE) - [Project website](http://graphite.readthedocs.org/) - [README](https://github.com/graphite-project/graphite-web/blob/master/README.md) - [Releases](https://github.com/graphite-project/graphite-web/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/graphite-project-graphite-web