Plotnine

0.15.3 · active · verified Thu Apr 09

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.

Warnings

breaking Calling `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.
breaking Plotnine v0.14.0 and newer require Python 3.10 or later.
Fix: Ensure your Python environment is version 3.10 or higher.
deprecated Several 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.
gotcha When 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() + ...)`).
gotcha When 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.
gotcha Plotnine'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`).

Install

pip install plotnine Basic installation
pip install 'plotnine[extra]' With optional dependencies (e.g., adjustText, geopandas)

Imports

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 *
```
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.

Quickstart

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

view raw JSON →