pygal.org

What is Pygal?

Pygal is a Python charting library for building charts in code and rendering them as images, most commonly as SVG. Its pitch is brevity: the documentation's own example creates a bar chart with labels and values in a single chained expression, then calls render() to produce the output.

What it is good at

• Vector output by default. SVG charts stay sharp at any size and are easy to embed in web pages or reports. SVG is also text, so you can style or post-process it.
• Terse, declarative code. You describe the chart type and pass data; Pygal handles axes, legends and layout. That suits scripts where a chart is one step in a longer pipeline.
• A broad chart vocabulary. Bar and line charts are the entry point, but the library also covers pie, radar, box, funnel, gauge, maps and more, so you can often avoid pulling in a second tool.
• Python-native data flow. Data comes from lists, database queries or computed results without an intermediate file format.

Where it fits, and where it does not

Reach for Pygal when you want a chart file produced by a Python program: scheduled reports, documentation builds, static site generation, notebooks, or a small web app that serves pre-rendered images. It is a poor fit for interactive dashboards with hover tooltips, zooming and live data streaming; those needs point to browser-side libraries instead. If you need pixel-perfect publication styling or statistical chart types like facets and regression layers, a heavier plotting library will be less friction.

A concrete scenario

Suppose you run a nightly job that summarises signups per region. With Pygal you can build a bar chart from a dictionary of region totals, write the SVG to disk, and reference it from an HTML email or report page — no JavaScript, no headless browser, no extra service. If the same report later needs interactive filtering, that is the signal to switch tools rather than extend this one.

Deciding between Pygal and alternatives

Next step

Start from the documentation's minimal example: create a chart object, pass your series, and call render() to see the SVG. Then check the chart-type list for the shape closest to your data before writing layout code. The project is documented at Pygal, and if you want a broader plotting toolkit for comparison, Matplotlib and Plotly cover the heavier and interactive ends of the spectrum respectively.

How do I create my first chart with Pygal?

Create a Bar chart, add one or more data series, and call render(). Pygal's own documentation shows the minimal pattern: instantiate pygal.Bar(), add values with .add(), then render.

import pygal

chart = pygal.Bar()
chart.add('Series 1', [1, 3, 3, 7])
chart.add('Series 2', [1, 6, 6, 4])
chart.render()

What each step does

• pygal.Bar() chooses the chart type. Swapping in Line, Pie, or XY changes the visual without changing the workflow.
• .add(label, values) appends one series. Call it again for each additional series; the label becomes the legend entry.
• .render() produces the chart output. In the documentation example this returns an SVG string, which is what makes Pygal convenient for embedding charts in web pages or saving them to files.

A concrete first run

If you are building a small dashboard, start with a bar chart of weekly counts:

import pygal

chart = pygal.Bar(title='Signups per week')
chart.x_labels = ['W1', 'W2', 'W3', 'W4']
chart.add('2025', [12, 19, 14, 22])
chart.add('2026', [15, 24, 18, 27])
chart.render_to_file('signups.svg')

Setting x_labels makes the bars readable, and render_to_file() writes the result directly rather than returning a string you have to handle yourself.

Choosing between output methods

Practical notes

Pygal's output is SVG by default, so it stays sharp at any size and is easy to style with CSS — a good fit for reports and web pages. PNG rendering depends on extra libraries, so treat it as a separate setup step rather than assuming it works out of the box. For interactive charts, Pygal also offers tooltips and hover behavior, but keep your first chart simple: get one series rendering before adding labels, titles, or multiple series.

Next step: after your first bar chart renders, change pygal.Bar() to pygal.Line() and reuse the same data to see how little the code changes.

How can I export a Pygal chart to PNG or SVG for use in a report or web page?

Pygal renders charts to SVG in the browser and can produce PNG through an image-rendering step, so it fits reports and web pages that want vector graphics by default. The page shows the basic pattern: build a chart object such as pygal.Bar(), pass data, then call .render().

SVG for reports and web pages

SVG is Pygal's native output and the better choice when the chart will be embedded in HTML or a PDF report, because it stays sharp at any size and remains editable as text.

import pygal

chart = pygal.Bar()
chart.add('Series A', [1, 3, 3, 7])
chart.add('Series B', [1, 6, 6, 4])

# Write SVG to a file
with open('chart.svg', 'w') as f:
    f.write(chart.render())

# Or get the SVG as a string for direct embedding
svg_data = chart.render(is_unicode=True)

For a web page, save the SVG and reference it with an <img> tag, or paste the SVG markup inline so the chart can inherit page styles and respond to CSS.

PNG for print and email

PNG is a raster format, so it suits contexts that cannot handle SVG, such as some email clients, Word documents, or slide decks. Pygal itself produces SVG, so a PNG export requires converting that SVG with an external tool. Common approaches:

• cairosvg converts an SVG string or file to PNG in Python.
• Inkscape or rsvg-convert convert on the command line in a build step.
• A browser or headless renderer can screenshot the SVG if you already render charts in an HTML page.

import cairosvg

svg_data = chart.render(is_unicode=True)
cairosvg.svg2png(bytestring=svg_data.encode('utf-8'), write_to='chart.png')

Decide by destination: SVG for HTML, PDF, and anything that may be resized; PNG for fixed-size print, email, and tools without SVG support. If you need PNG, plan the conversion step into your script rather than treating it as part of Pygal itself.

For broader charting comparisons, see Matplotlib and Plotly.

What steps are involved in installing Pygal and setting it up in a Python project?

Pygal installs like most pure-Python libraries: you add it to an environment with pip, import it, and build charts by chaining a chart type and a render() call. The documentation's own front page shows the minimal shape of a working script — a Bar chart, data series passed as iterables, and a final render() — so setup is mostly about getting the package into the right environment and choosing where the output goes.

Install into the environment you actually run

• Create and activate a virtual environment first, then run pip install pygal. This keeps Pygal and its dependencies out of your system Python and reproducible for teammates.
• If you manage dependencies declaratively, add pygal to your requirements.txt or project file rather than installing ad hoc, so a fresh checkout can rebuild the same environment.
• Confirm the install by importing it in a Python shell before writing chart code; an import error at this stage is far cheaper to debug than one buried in an application.

Verify with the smallest possible chart

The documentation's example is deliberately terse: instantiate a chart type, pass one or more data series, and call render(). A practical first check is to render a bar chart to a standalone SVG file and open it in a browser. If the file appears with the expected bars, your environment, import path and output handling are all working.

Decide the output format early

This is the setup decision that most affects the rest of your code:

Check the current API index in the Pygal documentation for the exact render methods and chart classes available in your installed version, since method names and options vary between releases.

A concrete starting scenario

Suppose you are adding a weekly-metrics panel to an internal Flask or Django app. Install Pygal in the app's virtual environment, write a small function that takes your query results and returns a rendered chart, then serve that output from a dedicated view. Keeping chart construction in one function means you can swap output formats later without touching your data layer.

Decision criteria for going further

• Need static images for email or PDFs: file-based rendering is the simplest fit.
• Need hover tooltips and legends in a browser: plan for the interactive rendering path from the start.
• Need several chart types: check the API index first, because available chart classes differ across versions.
• Working in a team: pin the Pygal version alongside your other dependencies so rendered output stays consistent.

How can I contribute to the Pygal project or report a bug?

Contribution to Pygal starts at its documentation site, which lists dedicated pages for Contributing, Installing, the Changelog and an API Index alongside the main docs. Those are the entry points to read before you touch code: the installation page tells you how to get a working local copy, and the changelog shows what has recently changed so you don't duplicate or contradict existing work.

For a bug, the practical route is to reproduce it against a current install, then check the changelog and issue tracker before filing. A useful report includes the Pygal version, the Python version, the exact chart call (for example a pygal.Bar() with its add() values), the renderer used, the full traceback, and the smallest snippet that still shows the problem. That last item matters more than prose: a maintainer can run a short snippet immediately, whereas a description of a chart that "looks wrong" usually needs a round of questions first.

Where different contributions fit

If you are unsure whether something is a bug or expected behaviour, open it as a question with your snippet rather than a bug claim. That is faster to resolve and avoids closing a report that was really a usage question.

As a concrete next step: install Pygal in a virtual environment, run the smallest chart that reproduces your issue, and paste that snippet with your version numbers into the project's tracker. The official documentation at Pygal is the authoritative place to confirm current contribution guidance before you submit.

What changes and new features are included in the latest Pygal release?

The Pygal documentation's own front page does not contain a release-notes section, so the authoritative place to look for changes in the latest version is the project's Changelog page, which the documentation index lists alongside Documentation, Installing, Contributing, and the API Index. In other words, the package's current version is stated as Pygal 3.0.5 in the documentation title, but the specific feature and fix list for that release lives in the changelog rather than in the landing page.

Where to check, and what to expect there

• Changelog — the primary source for added features, behavior changes, deprecations, and bug fixes per release.
• Installing — useful if a release note mentions a changed dependency or a new Python version requirement.
• API Index / Module Index — the fastest way to confirm whether a method, chart type, or option referenced in a changelog entry actually exists in the version you have installed.
• Pygal — the documentation home that links to all of the above.

A practical way to read a changelog for this kind of library

Pygal is a Python charting library, and its landing page demonstrates the characteristic style with a compact example: a Bar() chart taking series such as (1, 3, 3, 7) and (1, 6, 6, 4), followed by .render(). That matters for interpreting release notes, because changes in a charting library usually fall into a few recognizable buckets:

For a reader maintaining a reporting script, the decision rule is simple: if the changelog lists only additions, upgrading is usually low-risk and you can adopt the new feature at leisure. If it lists renames, removals, or output changes, test one representative chart end-to-end — build it, render it, and compare the file against your current output — before rolling the upgrade across a codebase.