Description
# plotnine <img width="20%" align="right" src="https://github.com/has2k1/plotnine/blob/logos/doc/images/logo-512.png?raw=true"> [](https://pypi.python.org/pypi/plotnine) [](https://pypi.python.org/pypi/plotnine) [](https://zenodo.org/badge/latestdoi/89276692) [](https://github.com/has2k1/plotnine/actions?query=branch%3Amain+workflow%3A%22build%22) [](https://codecov.io/github/has2k1/plotnine?branch=main) plotnine is an implementation of a *grammar of graphics* in Python based on [ggplot2](https://github.com/tidyverse/ggplot2). The grammar allows you to compose plots by explicitly mapping variables in a dataframe to the visual characteristics (position, color, size etc.) of objects that make up the plot. Plotting with a *grammar of graphics* is powerful. Custom (and otherwise complex) plots are easy to think about and build incrementally, while the simple plots remain simple to create. To learn more about how to use plotnine, check out the [documentation](https://plotnine.org). Since plotnine has an API similar to ggplot2, where it lacks in coverage the [ggplot2 documentation](http://ggplot2.tidyverse.org/reference/index.html) may be helpful. ## Example ```python from plotnine import * from plotnine.data import mtcars ``` Building a complex plot piece by piece. 1. Scatter plot ```python ( ggplot(mtcars, aes("wt", "mpg")) + geom_point() ) ``` <img width="90%" align="center" src="https://github.com/has2k1/plotnine/blob/logos/doc/images/readme-image-1.png?raw=true"> 2. Scatter plot colored according some variable ```python ( ggplot(mtcars, aes("wt", "mpg", color="factor(gear)")) + geom_point() ) ``` <img width="90%" align="center" src="https://github.com/has2k1/plotnine/blob/logos/doc/images/readme-image-2.png?raw=true"> 3. Scatter plot colored according some variable and smoothed with a linear model with confidence intervals. ```python ( ggplot(mtcars, aes("wt", "mpg", color="factor(gear)")) + geom_point() + stat_smooth(method="lm") ) ``` <img width="90%" align="center" src="https://github.com/has2k1/plotnine/blob/logos/doc/images/readme-image-3.png?raw=true"> 4. Scatter plot colored according some variable, smoothed with a linear model with confidence intervals and plotted on separate panels. ```python ( ggplot(mtcars, aes("wt", "mpg", color="factor(gear)")) + geom_point() + stat_smooth(method="lm") + facet_wrap("gear") ) ``` <img width="90%" align="center" src="https://github.com/has2k1/plotnine/blob/logos/doc/images/readme-image-4.png?raw=true"> 5. Adjust the themes I) Make it playful ```python ( ggplot(mtcars, aes("wt", "mpg", color="factor(gear)")) + geom_point() + stat_smooth(method="lm") + facet_wrap("gear") + theme_xkcd() ) ``` <img width="90%" align="center" src="https://github.com/has2k1/plotnine/blob/logos/doc/images/readme-image-5.png?raw=true"> II) Or professional ```python ( ggplot(mtcars, aes("wt", "mpg", color="factor(gear)")) + geom_point() + stat_smooth(method="lm") + facet_wrap("gear") + theme_tufte() ) ``` <img width="90%" align="center" src="https://github.com/has2k1/plotnine/blob/logos/doc/images/readme-image-5alt.png?raw=true"> ## Installation Official release ```console # Using pip $ pip install plotnine # 1. should be sufficient for most $ pip install 'plotnine[extra]' # 2. includes extra/optional packages $ pip install 'plotnine[test]' # 3. testing $ pip install 'plotnine[doc]' # 4. generating docs $ pip install 'plotnine[dev]' # 5. development (making releases) $ pip install 'plotnine[all]' # 6. everything # Or using conda $ conda install -c conda-forge plotnine # Or using pixi $ pixi init name-of-my-project $ cd name-of-my-project $ pixi add python plotnine ``` Development version ```console $ pip install git+https://github.com/has2k1/plotnine.git ``` ## Contributing Our documentation could use some examples, but we are looking for something a little bit special. We have two criteria: 1. Simple looking plots that otherwise require a trick or two. 2. Plots that are part of a data analytic narrative. That is, they provide some form of clarity showing off the `geom`, `stat`, ... at their differential best. If you come up with something that meets those criteria, we would love to see it. See [plotnine-examples](https://github.com/has2k1/plotnine-examples). If you discover a bug checkout the [issues](https://github.com/has2k1/plotnine/issues) if i
Release History
| Version | Changes | Urgency | Date |
|---|---|---|---|
| 0.15.3 | Imported from PyPI (0.15.3) | Low | 4/21/2026 |
| v0.15.3 | ### Enhancements - Removed warnings about copy-on-write for pandas >= 3.0.0 **Full Changelog**: https://github.com/has2k1/plotnine/compare/v0.15.2...v0.15.3 | Low | 1/29/2026 |
| v0.15.2 | ### Bug Fixes - Fixed random failures for when using plotnine in quarto == 1.8.26. #1017 **Full Changelog**: https://github.com/has2k1/plotnine/compare/v0.15.1...v0.15.2 | Low | 12/12/2025 |
| v0.15.1 | ## What's Changed * Do not overwrite labels set with labs by @has2k1 in https://github.com/has2k1/plotnine/pull/958 * Fix changing composition figure size when plot_spacer is the last plot by @has2k1 in https://github.com/has2k1/plotnine/pull/961 * Fix stat_quantile to handle formula that use environment variables by @has2k1 in https://github.com/has2k1/plotnine/pull/964 * Add missing scale_stroke_identity by @has2k1 in https://github.com/has2k1/plotnine/pull/965 * Prefer `_repr_mimebundle_ | Low | 11/3/2025 |
| v0.15.0 | ### API Changes - Themeables `axis_ticks_pad`, `axis_ticks_pad_minor`, `axis_ticks_pad_major`, `axis_ticks_pad_minor_x`, `axis_ticks_pad_minor_y`, `axis_ticks_pad_major_x` and `axis_ticks_pad_major_y` have been deprecated. Use the `margin` parameter of [`element_text`](https://plotnine.org/reference/element_text.html#plotnine.element_text) with `axis_text`, `axis_text_x` or `axis_text_y` to control the spacing between the axis text and the ticks. ([#843](https://github.com/has2k1/plotnine/iss | Low | 7/15/2025 |
| v0.14.6 | This release prevents plotnine from pulling in scipy v1.16.0 because it does not play well with [statsmodels](https://github.com/statsmodels/statsmodels/issues/9584). | Low | 6/25/2025 |
| v0.14.5 | ## Fixes Fixed [geom_text](https://plotnine.org/reference/geom_text.html#plotnine.geom_text) with `adjust_text` so that the the arrows are drawn between layers with the text/label on top. | Low | 1/2/2025 |
| v0.14.4 | ## Bug Fixes - Fixed [geom_text](https://plotnine.org/reference/geom_text.html#plotnine.geom_text) with adjust_text so that the the arrows are drawn at the same layer (zorder) as the text. - Fixed [geom_text](https://plotnine.org/reference/geom_text.html#plotnine.geom_text) with adjust_text for some cases where the text are placed outside the panels. [#899](https://github.com/has2k1/plotnine/issues/899) - The default aesthetics and aesthetic parameters of geoms (and stats) are now transfo | Low | 12/16/2024 |
| v0.14.3 | ## Enhancements - Got rid of a logging information about the fontsize that is recorded for all plots that have a legend. ([#889](https://github.com/has2k1/plotnine/issues/889)) - When using [geom_text](https://plotnine.org/reference/geom_text.html#plotnine.geom_text) with adjust_text, some sensible default arrow properties will be applied. - Changed the threshold number of keys for when the legend is split into multiple columns from 20 to 15. This only applies in the default case when the u | Low | 11/26/2024 |
| v0.14.2 | ## Bug Fixes - Fixed bugs that affected [geom_dotplot](https://plotnine.org/reference/geom_dotplot.html#plotnine.geom_dotplot) and [geom_sina](https://plotnine.org/reference/geom_sina.html#plotnine.geom_sina) where data with an index that did not include 0 led to a crash. ([#888](https://github.com/has2k1/plotnine/issues/888)) - Fixed v0.14.0 regression that made `scale_color_cmap_d` unusable. ([#890](https://github.com/has2k1/plotnine/issues/890)) | Low | 11/21/2024 |
| v0.14.1 | ## Bug Fixes - Fix expansion of datetime and timedelta scales when using both the lower and upper addition constants. - In quarto documents make the output `retina` even if the `fig-format` is png. - Fixed bug where you could not save as pdf if also specifying the `aspect_ratio`. ([#885](https://github.com/has2k1/plotnine/issues/885)) | Low | 11/5/2024 |
| v0.14.0 | ## API Changes - You cannot call `print` on a ggplot object to show it. This was deprecated in `v0.13.0` and it has now been removed. Use [ggplot.show()](https://plotnine.org/reference/ggplot.html#plotnine.ggplot.show) - The color_space parameter of [scale_color_hue](https://plotnine.org/reference/scale_color_hue.html#plotnine.scale_color_hue) now accepts the value `"hlsuv"` instead of `"husl"`. The meaning of has not changed, and `"husl"` is silently accepted. - Themeables `axis_ticks_ | Low | 10/29/2024 |
| v0.13.6 | **Bug Fixes** - Fixed [geom_label](https://plotnine.org/reference/geom_label.html#plotnine.geom_label) to work with a boxstyle of any following square, circle, darrow, larrow, rarrow, roundtooth or sawtooth.([#779](https://github.com/has2k1/plotnine/issues/779)) **Enhancements** - Stopped spurious warnings of the form PlotnineWarning: Failed to apply `after_scale` modifications to the legend. when the after_scale mapping is for another aestetic. - Added width and height as default aesthe | Low | 5/10/2024 |
| v0.13.5 | **Bug Fixes** - Fixed bug in [stat_smooth](https://plotnine.org/reference/stat_smooth.html#plotnine.stat_smooth) where you could not set the family when using a glm. ([#769](https://github.com/has2k1/plotnine/issues/769)) - Fixed bug in [position_dodge2](https://plotnine.org/reference/position_dodge2.html#plotnine.position_dodge2) the widths of the dodged objects were mixed up. ([#772](https://github.com/has2k1/plotnine/issues/772)) - Fixed [geom_text](https://plotnine.org/reference/geom_te | Low | 4/26/2024 |
| v0.13.4 | **Bug Fixes** Fixed regression in v0.13.3 where setting some text elements element_blank led to an error. [#764](https://github.com/has2k1/plotnine/issues/764) | Low | 4/3/2024 |
| v0.13.3 | This is a small bug fix release. **Bug Fixes** - Fixed layout manager to make space for the `strip_text` when there is no `strip_background`. ([#760](https://github.com/has2k1/plotnine/issues/760)) - Made the default position of `guide_legend` text to be right. ([#761](https://github.com/has2k1/plotnine/issues/761)) - Fixed aligning (ha & va) of `plot_title`, `plot_subtitle`, `plot_caption`, `axis_title_x`, `axis_title_y` to work with float values in the range `[0, 1]`. | Low | 3/27/2024 |
| v0.13.2 | This release has a single enhancement. When drawing a plot, pandas copy-on-write is turned off. This prevents errors for users who have turned it on. A later release will make plotnine capable of working with copy-on-write on. | Low | 3/15/2024 |
| v0.13.1 | ## v0.13.1 ### Bug Fixes - Fixed a bug where a legend with blank title or text could result in a wrong justification. - Fixed a bug where setting legend justification to a string i.e one of `left`, `right`, `top`, `bottom`, `center` had no effect. | Low | 3/6/2024 |
| v0.13.0 | ### API Changes - Requires python \>= 3.9 - Using the `print` or `repr` functions to draw and show the plot has been deprecated. Use [ggplot.show()](./reference/ggplot.html#plotnine.ggplot.show). - The name of the calculated aesthetic of [`stat_function`](./reference/stat_function.html#plotnine.stat_function) changed from `y` to `fx`. - [`stat_ecdf`](./reference/stat_ecdf.html#plotnine.stat_ecdf) has gained the `pad` parameter. The default is set to `True`, which pads the domain with | Low | 2/20/2024 |
| v0.12.4 | This is a maintenance release with a few changes, see the [changelog](https://plotnine.readthedocs.io/en/v0.12.4/changelog.html#v0-12-4). | Low | 11/6/2023 |
| v0.12.3 | A maintenance release. See [changelog](https://plotnine.readthedocs.io/en/v0.12.3/changelog.html#v0-12-3). | Low | 9/1/2023 |
| v0.12.2 | This release is exactly the same as the last one (v0.12.1), except that it requires `0.9.0 <= mizani < 0.10.0`, whereas the last one requires `0.9.0 <= mizani`. | Low | 7/21/2023 |
| v0.12.1 | (2023-05-09) ### New Features - A layout manager. Now you do not have to adjust spacing parameters to prevent objects around the panels from overlapping. Specifically, you can: 1. Set the legend position to "top", "left" or "bottom" 2. Use a large or multiline plot title 3. Use a large or multiline plot caption 4. Use [facet_wrap](https://plotnine.readthedocs.io/en/stable/generated/plotnine.facets.facet_wrap.html#plotnine.facets.facet_wrap) with `scales="free"` `sca | Low | 5/10/2023 |
| v0.9.0 | See the [changelog](https://plotnine.readthedocs.io/en/stable/changelog.html#v0-9-0). | Low | 9/29/2022 |
| v0.10.1 | See the [changelog](https://plotnine.readthedocs.io/en/stable/changelog.html#v0-10-1). | Low | 9/29/2022 |
| v0.10.0 | See the [changelog](https://plotnine.readthedocs.io/en/stable/changelog.html#v0-10-0). | Low | 9/29/2022 |
| v0.8.0 | ## API Changes - How you map to calculated aesthetics has changed. Use the `~plotnine.aes.after_stat` function. The old methods `'stat(name)'` and `'..name..'` have been deprecated. ## New Features - You can now map to aesthetics at three different stages. See `~plotnine.aes.aes`, `~plotnine.aes.after_stat`, `~plotnine.aes.after_scale` and `~plotnine.aes.stage`. - `~plotnine.geoms.geom_violin` gained the a new parameter `style` with which you can draw hal | Low | 3/25/2021 |
| v0.7.1 | v0.7.1 is a small bugfix and maintenance release. See the official [changelog](https://plotnine.readthedocs.io/en/stable/changelog.html#v0-7-1) for details. A copy of the changes is also copied below. ------------------- ## Bug Fixes - Fixed issue where a plot has no data and the geoms have no data, but the mappings are valid. (`404`) - Fixed `preserve='single'` in `plotnine.positions.position_dodge` and `plotnine.positions.position_dodge2` to work for geoms that only have `x | Low | 8/5/2020 |
| v0.7.0 | This is a large release with many bug fixes and enhancements. See offical [changelog](https://plotnine.readthedocs.io/en/stable/changelog.html#v0-7-0). A version of the changes is included below.] --------------- ### API Changes[¶](#api-changes "Permalink to this headline") - Changed the default method of caculating bandwidth for all stats that use kernel density estimation. The affected stats are [`stat_density`](https://plotnine.readthedocs.io/en/stable/generated/plotnine.stats.stat_d | Low | 6/5/2020 |
| v0.6.0 | This release has many changes, check out the [changelog](https://plotnine.readthedocs.io/en/stable/changelog.html#v0-6-0). A version of the changes is included below. ---------------------- ## API Changes - The `draw` parameter of `geom_map` has been removed. Shapefiles should contain only one type of geometry and that is the geometry that is drawn. - Ordinal (Ordered categorical) columns are now mapped to ordinal scales. This creates different plots. - The default mapping for the | Low | 8/21/2019 |
| v0.5.1 | This release only updates the version requirement for the mizani project. See [changelog](https://plotnine.readthedocs.io/en/stable/changelog.html#v0-5-1) | Low | 10/17/2018 |
| v0.5.0 | A copy of the [changelog](https://plotnine.readthedocs.io/en/stable/changelog.html#v0-5-0) is pasted below. -------------------- ### API Changes - Plotnine 0.5.0 only supports Python 3.5 and higher - geopandas has been removed as a requirement for installation. Users of `geom_map` will have to install it separately. (178) ### Bug Fixes - Fixed issue where with the `subplots_adjust` themeable could not be used to set the wspace and hspace Matplotlib subplot parameters. (185) | Low | 10/16/2018 |
| v0.4.0 | This is a big release with many improvements and bug-fixes. See the official [changelog](https://plotnine.readthedocs.io/en/latest/changelog.html#v0-4-0) for details. Copy of the changelog ------------- **API Changes** - Calculated aesthetics are accessed using the stat() function. The old method (double dots ..name..) still works. - stat_qq calculates slightly different points for the theoretical quantiles. - The scales (when set to free, free_x or free_y') parameter of facet_grid an | Low | 8/1/2018 |
| v0.3.0 | Big release with known bugs fixed and new features. A copy of the [changelog](http://plotnine.readthedocs.io/en/stable/changelog.html#v0-3-0) is pasted below. --------------------------------- # API Changes - ~plotnine.geoms.geom\_smooth gained an extra parameter `legend_fill_ratio` that control the area of the legend that is filled to indicate confidence intervals. (32) - plotnine.ggplot.save gained an extra parameter `verbose`. It no longer guesses when to print | Low | 11/8/2017 |
| v0.2.0 | Fixes - Fixed bug in scale_x_discrete and scale_y_discrete where if they were instantiated with parameter limits that is either a numpy array or a pandas series, plotting would fail with a ValueError. - Fixed exceptions when using pandas.pivot_table() for Pandas v0.20.0. The API was fixed. - Fixed issues where lines/paths with segments that all belonged in the same group had joins that in some cases were “butted”. API Changes - geom_text now uses ha and va as parameter names for the h | Low | 5/18/2017 |
| v0.1.0 | First public release | Low | 4/28/2017 |