plotnine

library0.15.8pypypi✓ verified 23d ago

Plotnine is a Python package for data visualization, implementing a grammar of graphics inspired by R's ggplot2. It allows users to compose plots by explicitly mapping data variables to visual aesthetics, making it powerful for creating custom and complex visualizations incrementally. The library is actively maintained, with frequent releases. The current stable version is 0.15.3.

data

pip install plotnine

github ↗package ↗homepage ↗changelog ↗

INSTALL

IMPORT

SIG · PLOTNINE

plotnine

datapythonv0.15.8

Install

24.2s avg

Import

1714ms

Disk

507MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.15.8 · 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

musl

glibc

py 3.10

1/2 runs

✓ 24.3s

py 3.11

1/2 runs

✓ 24.1s

py 3.12

1/2 runs

✓ 24.4s

py 3.13

1/2 runs

✓ 24.4s

py 3.9

✕ build_error

✓ 23.65s

507MB installed

● package 507MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ggplot, aes, geom_point

✓ from plotnine import ggplot, aes, geom_point

Importing specific components is generally preferred for clarity and avoiding namespace pollution.

✓ from plotnine import *

✗ import plotnine

While 'from plotnine import *' is common in examples for brevity, directly importing 'plotnine' does not expose the core functions (ggplot, aes, geoms) directly, requiring `plotnine.ggplot(...)`, etc. which is not idiomatic.

This example creates a scatter plot of bill length vs. bill depth, colored by penguin species, using the built-in `penguins` dataset. It demonstrates the fundamental `ggplot`, `aes`, and `geom_point` components of plotnine.

import pandas as pd from plotnine import ggplot, aes, geom_point from plotnine.data import penguins # Create a basic scatter plot using the built-in penguins dataset plot = (ggplot(penguins, aes(x='bill_length_mm', y='bill_depth_mm', color='species')) + geom_point()) # To display the plot (e.g., in a script or non-notebook environment) # plot.show() # In a Jupyter notebook or interactive environment, simply having the # plot object as the last line will display it. plot

Debug

Known issues

breakingCalling `print(ggplot_obj)` no longer renders the plot; it now returns the display size in pixels. This change was fully implemented in v0.14.0 after being deprecated in v0.13.0.

fix

Use `ggplot_obj.show()` to explicitly display the plot, especially in scripts or non-notebook environments where the plot object isn't implicitly rendered.

affects: >=0.14.0

breakingPlotnine v0.14.0 and newer require Python 3.10 or later.

fix

Ensure your Python environment is version 3.10 or higher.

affects: >=0.14.0

deprecatedSeveral themeables related to axis tick padding (e.g., `axis_ticks_pad`, `axis_ticks_pad_minor_x`) have been deprecated in v0.15.0.

fix

Use the `margin` parameter of `element_text` with `axis_text`, `axis_text_x`, or `axis_text_y` to control spacing between axis text and ticks.

affects: >=0.15.0

gotchaWhen constructing multi-line plots using the `+` operator, forgetting to wrap the entire expression in parentheses can lead to `SyntaxError` or incorrect parsing.

fix

Always enclose multi-line plot constructions within parentheses (e.g., `(ggplot(...) + geom_point() + ...)`).

affects: All versions

gotchaWhen mapping aesthetics, `aes()` expects column names as strings for mapping data to visual properties. Manually setting a constant aesthetic (e.g., making all points blue) should be done outside `aes()` as a direct argument to the geom.

fix

For data mapping: `aes(color='column_name')`. For manual setting: `geom_point(color='blue')`. Do NOT use `aes(color='blue')` to set a constant color.

affects: All versions

gotchaPlotnine's dependency on `mizani` (for scales) can sometimes lead to version conflicts with other packages, particularly in older installations.

fix

Always install `plotnine` and its dependencies in a fresh virtual environment. If issues arise, check the `mizani` version specified in `plotnine`'s `pyproject.toml` on GitHub and consider pinning `mizani` to a compatible version if necessary (e.g., `pip install mizani==x.y.z`).

affects: <0.14.0

Errors

Common errors & fixes

No `x` aesthetic found. A `x` aesthetic is required by `geom_point`.

A required aesthetic (like 'x' or 'y') for a specific geom function was not provided within the `aes()` mapping.

fix

Ensure all mandatory aesthetics for the chosen `geom` are mapped from your data within `aes()` (e.g., `ggplot(df, aes(x='column_name_x', y='column_name_y')) + geom_point()`).

KeyError: 'column_name'

You are attempting to map an aesthetic to a column name that does not exist in the DataFrame provided to `ggplot()` or a specific `geom`.

fix

Verify that the column name specified in `aes()` exactly matches an existing column in your DataFrame, including case sensitivity, or create the column if it's missing.

ModuleNotFoundError: No module named 'matplotlib._contour'

This error typically occurs when `plotnine` is used with an incompatible version of `matplotlib`, often a newer `matplotlib` version (e.g., 3.6+) that has moved or removed internal modules that `plotnine` relies on.

fix

Downgrade `matplotlib` to a compatible version (e.g., `pip install 'matplotlib<3.6'`) or upgrade `plotnine` to its latest version that supports newer `matplotlib` releases (`pip install --upgrade plotnine`).

Could not evaluate the given string as a column name

You are attempting to set a fixed aesthetic value (e.g., `color='blue'`) inside the `aes()` mapping, but `aes()` is strictly for mapping data variables to aesthetics, not for setting constant visual properties.

fix

Move fixed aesthetic assignments outside of `aes()`, directly as arguments to the `geom_` function (e.g., `geom_point(color='blue')` instead of `geom_point(aes(color='blue'))`).

Upgrade

Version history

0.15.8latest on PyPI · released Aug 14, 2026

Audit

Dependencies

matplotlibrequiredBackend for rendering plots.

pandasrequiredPrimary DataFrame support.

mizanirequiredProvides scales for plotnine.

numpyrequiredNumerical operations.

scipyrequiredScientific computing, used in some stats.

statsmodelsrequiredStatistical models, used in some stats.

adjustTextoptionalAutomatic label placement (optional, part of 'extra').