{"id":2191,"library":"plotnine","title":"Plotnine","description":"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.","status":"active","version":"0.15.3","language":"python","source_language":"en","source_url":"https://github.com/has2k1/plotnine","tags":["data visualization","ggplot2","grammar of graphics","plotting","statistics"],"install":[{"cmd":"pip install plotnine","lang":"bash","label":"Basic installation"},{"cmd":"pip install 'plotnine[extra]'","lang":"bash","label":"With optional dependencies (e.g., adjustText, geopandas)"}],"dependencies":[{"reason":"Backend for rendering plots.","package":"matplotlib","version_constraint":">=3.8.0"},{"reason":"Primary DataFrame support.","package":"pandas","version_constraint":">=2.2.0"},{"reason":"Provides scales for plotnine.","package":"mizani","version_constraint":"~=0.14.0"},{"reason":"Numerical operations.","package":"numpy","version_constraint":">=1.23.5"},{"reason":"Scientific computing, used in some stats.","package":"scipy","version_constraint":">=1.8.0"},{"reason":"Statistical models, used in some stats.","package":"statsmodels","version_constraint":">=0.14.6"},{"reason":"Automatic label placement (optional, part of 'extra').","package":"adjustText","optional":true,"version_constraint":">=1.2.0"},{"reason":"Working with geographic data (optional, part of 'extra').","package":"geopandas","optional":true,"version_constraint":">=1.0.0"},{"reason":"Gaussian Process smoothing (optional, part of 'extra').","package":"scikit-learn","optional":true,"version_constraint":">=1.3.0"},{"reason":"LOESS smoothing (optional, part of 'extra').","package":"scikit-misc","optional":true,"version_constraint":">=0.5.1"},{"reason":"Alternative DataFrame support (optional, part of 'extra').","package":"polars","optional":true,"version_constraint":">=1.24.0"},{"reason":"Required for Polars integration (optional, part of 'extra').","package":"pyarrow","optional":true,"version_constraint":">=19.0.1"}],"imports":[{"note":"Importing specific components is generally preferred for clarity and avoiding namespace pollution.","symbol":"ggplot, aes, geom_point","correct":"from plotnine import ggplot, aes, geom_point"},{"note":"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.","wrong":"import plotnine","symbol":"*","correct":"from plotnine import *"}],"quickstart":{"code":"import pandas as pd\nfrom plotnine import ggplot, aes, geom_point\nfrom plotnine.data import penguins\n\n# Create a basic scatter plot using the built-in penguins dataset\nplot = (ggplot(penguins, aes(x='bill_length_mm', y='bill_depth_mm', color='species')) +\n        geom_point())\n\n# To display the plot (e.g., in a script or non-notebook environment)\n# plot.show()\n\n# In a Jupyter notebook or interactive environment, simply having the\n# plot object as the last line will display it.\nplot","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.14.0"},{"fix":"Ensure your Python environment is version 3.10 or higher.","message":"Plotnine v0.14.0 and newer require Python 3.10 or later.","severity":"breaking","affected_versions":">=0.14.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.","message":"Several themeables related to axis tick padding (e.g., `axis_ticks_pad`, `axis_ticks_pad_minor_x`) have been deprecated in v0.15.0.","severity":"deprecated","affected_versions":">=0.15.0"},{"fix":"Always enclose multi-line plot constructions within parentheses (e.g., `(ggplot(...) + geom_point() + ...)`).","message":"When constructing multi-line plots using the `+` operator, forgetting to wrap the entire expression in parentheses can lead to `SyntaxError` or incorrect parsing.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"Plotnine's dependency on `mizani` (for scales) can sometimes lead to version conflicts with other packages, particularly in older installations.","severity":"gotcha","affected_versions":"<0.14.0"}],"env_vars":null,"search_vec":"'0.15.3':57 'activ':47 'aesthet':33 'allow':21 'complex':41 'compos':24 'creat':38 'current':53 'custom':39 'data':8,29,58 'explicit':27 'frequent':50 'ggplot2':19,60 'grammar':12,61 'graphic':14,63 'implement':10 'increment':43 'inspir':15 'librari':45 'maintain':48 'make':34 'map':28 'packag':6 'plot':25,64 'plotnin':1,2 'power':36 'python':5 'r':17 'releas':51 'stabl':54 'statist':65 'user':22 'variabl':30 'version':55 'visual':9,32,42,59","created_at":"2026-04-09T18:47:24.350281+00:00","updated_at":"2026-04-16T18:04:11.066998+00:00","problems":[{"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()`).","cause":"A required aesthetic (like 'x' or 'y') for a specific geom function was not provided within the `aes()` mapping.","error":"No `x` aesthetic found. A `x` aesthetic is required by `geom_point`."},{"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.","cause":"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`.","error":"KeyError: 'column_name'"},{"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`).","cause":"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.","error":"ModuleNotFoundError: No module named 'matplotlib._contour'"},{"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'))`).","cause":"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.","error":"Could not evaluate the given string as a column name"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.15.8","cli_name":"","cli_version":null,"type":"library","homepage":"https://plotnine.readthedocs.io/en/stable","github":"https://github.com/has2k1/plotnine","docs":null,"changelog":"https://plotnine.readthedocs.io/en/stable/changelog.html","pypi":"https://pypi.org/project/plotnine/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}