# Pygal: SVG Charts as Python Objects, Not Pixels

> Pygal renders charts into SVG through a Python API that mirrors the data structure, which makes it a good fit for generated reports and a poor fit for dense scientific plotting. Here is what the repository actually documents, and what it leaves open.

**Kozea/pygal** — PYthon svg GrAph plotting Library

- Repository: https://github.com/Kozea/pygal
- Website: https://www.pygal.org
- Stars: 2,771 · Forks: 419
- Language: Python
- License: LGPL-3.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/kozea-pygal

## The problem Pygal solves: charts that are files, not windows

Most Python plotting libraries assume you are sitting in front of the output. You call a show function and a window appears, or you build a figure object for a notebook cell. Pygal takes the opposite position. The README describes it as "a dynamic SVG charting library written in python", and the emphasis lands on SVG: the output of a chart is markup, a document you can write to disk, embed in HTML, or hand to a browser.

That matters for a specific class of work. Scheduled report generators, static site builds, PDF pipelines and email digests all need charts that exist without a running plotting session. An SVG file fits those pipelines because it is text. You can diff it, minify it, post-process it with an XML tool, or inline it into a page template. The README points to www.pygal.org for the full documentation, which is where the chart-type catalogue lives rather than in the repository README.

The audience is therefore narrower than "anyone who plots data in Python". It is developers who treat a chart as one more artifact their program emits, alongside a JSON file or an HTML fragment. If your chart is the final thing a human looks at interactively, Pygal is the wrong shape.

## How the object model maps data onto SVG

Pygal's API is declarative in a way that mirrors the chart itself. You instantiate a chart class, add data series, and call a render method. The chart object holds the configuration, the series hold the values, and rendering walks that structure to emit SVG elements.

This is why the library can describe itself as dynamic without shipping a JavaScript runtime. Interactivity in the output is expressed as SVG features and embedded behaviour rather than a separate rendering engine, and the chart object is the single place where both data and presentation are decided. The practical consequence is that a chart is reproducible: the same object produces the same markup, so a chart can be regenerated in CI and compared.

The repository layout reflects the same split. The pygal/ package holds the library, demo/moulinrouge.py plus the demo/moulinrouge/ directory hold a worked example, and pygal_gen.py is installed as a script entry point according to setup.py. The Makefile exposes a visual-check target that runs demo/moulinrouge.py, which is the repository's own way of eyeballing output during development. The demo also declares its own dependencies: flask, pygal_maps_ch, pygal_maps_fr and pygal_maps_world. Those three map packages are separate distributions, not part of the core install, which is worth knowing before you assume a world map works out of the box.

## Installing Pygal and drawing a first chart

The README gives one installation line. The package is on PyPI under the name pygal, and setup.py declares python_requires=">=3.8", so anything older than Python 3.8 is out of scope.

```bash
pip install pygal
```

After that, the README's own test instructions are the next thing you can actually run. Pygal is tested with py.test, and the README shows both commands:

```bash
pip install pytest
py.test
```

For the full visual demo, the Makefile target is the shortest path:

```bash
make visual-check
```

That target runs demo/moulinrouge.py. Note that it depends on flask and the three map packages listed in setup.py's demo requirements, so install those first or the demo will fail on import. The README does not include a chart-construction example; the API for individual chart types is documented on www.pygal.org, and demo/moulinrouge.py is the worked example in the repository itself.

## Where Pygal stops being the right tool

The honest limitation is the one the output format implies. SVG is a document format, and documents do not scale to hundreds of thousands of elements. A scatter plot with a million points becomes a million SVG nodes, and the browser that opens it will suffer. Pygal's design goal is presentable, embeddable charts, not high-density data exploration.

There is a second, quieter constraint. The README is thin. It covers installation, testing, contribution and licensing, and then defers everything else to www.pygal.org. Nothing in the repository README documents error handling for malformed series, behaviour when a series has fewer values than the category labels, or what happens with missing data points. If you need those answers, you will be reading the documentation site and the source, not the README.

The repository layout also shows that the map chart types live outside the core package. pygal_maps_world, pygal_maps_fr and pygal_maps_ch are separate distributions referenced in setup.py's demo requirements. Anyone expecting a geographic chart from a bare pip install pygal will not get one.

Finally, Pygal is a rendering library, not an analysis library. There is no resampling, no binning, no statistical layer. You compute the numbers elsewhere and hand Pygal the result.

## Pygal versus Matplotlib and Plotly

The comparison people search for is pygal vs matplotlib, and the difference is architectural rather than cosmetic. Matplotlib is a general plotting system with a rendering backend abstraction; its default output is a raster image, and it can also emit SVG. It carries a large API surface for axes, ticks, layouts and subplots, and it is the tool people reach for when the chart itself needs fine-grained control.

Pygal skips the backend abstraction and targets SVG directly. The API is smaller and the chart object is the configuration surface. That trade buys simplicity for generated reports and costs flexibility for bespoke layouts. If you need a polar projection with custom tick placement, Matplotlib has the vocabulary and Pygal does not.

Against Plotly the split is different again. Plotly's strength is interactive output backed by a JavaScript library, which means the chart's behaviour lives in the browser. Pygal keeps everything in the SVG document. For a static report that is an advantage: no script tag, no CDN dependency, no version drift in a client-side library. For an exploratory dashboard it is a limitation, because the interaction model is whatever SVG and the embedded markup allow, not a full plotting runtime.

The repository's own demo is the fairest test of fit. If the charts in demo/moulinrouge/ look like the charts you need to produce, Pygal's model will feel natural. If they do not, no amount of configuration will close the gap.

## Licence, maintenance and the cost of upgrading

Pygal is released under LGPL-3.0. The setup.py header states the terms: you may redistribute it and modify it under the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 or any later version, and it is distributed without warranty. The practical question for a product team is whether LGPL-3.0 fits how you ship. Because the licence is the Lesser GPL, the usual consideration is dynamic linking versus static incorporation, and that is a question for your own legal review rather than something this article can settle.

The repository is not archived. The last push was on 2026-07-21, and the most recent release listed is 3.1.3 on 2026-06-18, with 3.1.2 on the same day and 3.1.1 on 2026-06-02. Those dates indicate a project that still receives commits and tagged releases, though the spacing of patch releases is the only maintenance signal available here.

Upgrade cost is bounded by the dependency footprint. The core package's test requirements in setup.py are cairosvg, coveralls, lxml, pyquery, pytest, pytest-cov and ruff>=0.5.6. Those are development and test dependencies, not runtime ones, which keeps the install light. The Python floor is 3.8, so an environment pinned below that cannot use the current release. If you rely on the map packages, track them separately, since they version independently of the core library.

## Conclusion

Pygal suits developers who generate charts as files or markup inside a Python pipeline and want the SVG to be inspectable and stylable afterward. It does not suit anyone who needs interactive panning, zooming or million-point rendering; that is what Matplotlib or Plotly are for. Before adopting it, run the demo/moulinrouge.py example from the repository to see the full range of chart types, confirm which optional map packages you need (pygal_maps_world, pygal_maps_fr, pygal_maps_ch), and check that LGPL-3.0 is compatible with how you ship your own code.

## FAQ

### How do I install Pygal?

The README gives a single command: pip install pygal. The package requires Python 3.8 or newer according to setup.py, and the map chart types need separate packages such as pygal_maps_world.

### How do you use Pygal in Python?

You create a chart object, add one or more named series to it, and call a render method to produce SVG markup, either as a string or written to a file. The full chart-type catalogue is on www.pygal.org rather than in the README.

### What is Pygal in Python?

Pygal is a dynamic SVG charting library written in Python, distributed under LGPL-3.0. It renders charts as SVG documents rather than raster images or interactive JavaScript widgets.

### How does Pygal compare with Plotly?

Plotly produces interactive charts whose behaviour runs in the browser through a JavaScript library, while Pygal emits a self-contained SVG document with no client-side runtime. For static reports the Pygal approach avoids a CDN dependency; for exploratory dashboards the Plotly approach offers more interaction.

### What does Pygal mean?

The name is an acronym for PYthon svg GrAph plotting Library, as given in the repository description. The README itself only expands it as a dynamic SVG charting library written in Python.

### What is Pygal used for?

Pygal is used to produce SVG charts from Python data, so the result is a document you can write to disk or embed in a page rather than an interactive window. The README points to www.pygal.org for the documentation covering the available chart types.

## Sources

- [Kozea/pygal on GitHub](https://github.com/Kozea/pygal)
- [License: LGPL-3.0](https://github.com/Kozea/pygal/blob/master/LICENSE)
- [Project website](https://www.pygal.org)
- [README](https://github.com/Kozea/pygal/blob/master/README.md)
- [Releases](https://github.com/Kozea/pygal/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kozea-pygal