ggplot2: The Grammar of Graphics in R, and What It Refuses to Do

What ggplot2 solves, and who it is actually for

Base R plotting asks you to draw. You call plot(), then lines(), then points(), and the state of the device carries over between calls. ggplot2 inverts that. According to the README, you "provide the data, tell ggplot2 how to map variables to aesthetics, what graphical primitives to use, and it takes care of the details." The output is a description of a plot, not a sequence of drawing commands.

That distinction matters most when plots are produced repeatedly. A mapping from a column to the x axis, a colour scale, and a facet definition can be reused across datasets with the same shape. The person writing the code is not the person reading the chart, and the grammar gives both of them the same vocabulary. The README frames this as a "deep philosophy of visualisation," which is a fair warning: ggplot2 is not a shortcut for people who want to avoid learning a plotting model. It is a shortcut for people who want the model.

The audience is R users producing statistical graphics, from a single exploratory scatterplot to a report that runs on a schedule. If your output is an interactive web dashboard, the grammar still applies, but the rendering layer is a separate concern.

The layered model: aes(), geoms, scales, facets, coordinates

A ggplot2 plot is assembled by addition. You start with ggplot(), supply a dataset and an aesthetic mapping with aes(), then add components. The README lists the four kinds of component you add: layers such as geom_point() or geom_histogram(), scales such as scale_colour_brewer(), faceting specifications such as facet_wrap(), and coordinate systems such as coord_flip().

The mapping is the part that carries the design. aes() does not hold data. It holds expressions that name columns, and those expressions are evaluated later against whatever data each layer supplies. That is why a layer can override the plot-level data or the plot-level mapping, and why a single mapping can drive a legend that is assembled from the layers that use it.

Scales are where most of the practical work happens. A scale controls both the transformation from data to visual value and the legend or axis that reports it. Faceting splits the data into panels by one or two variables and applies the same layers in each panel. Coordinates change the geometry of the panel itself, not the data. Once you can name which of these five things you are changing, most ggplot2 questions stop being mysterious.

Installing ggplot2 and drawing a first real plot

The README gives three install routes. The first two are the normal ones for a released version. The third builds from the GitHub repository and requires the pak package.

# The easiest way to get ggplot2 is to install the whole tidyverse:
install.packages("tidyverse")

# Alternatively, install just ggplot2:
install.packages("ggplot2")

# Or the development version from GitHub:
# install.packages("pak")
pak::pak("tidyverse/ggplot2")

After install.packages("ggplot2") finishes, library(ggplot2) should load without a message about a missing dependency. The repository's DESCRIPTION file and NAMESPACE are the two places to look if a version conflict appears, since the package's imports are declared there rather than in the README.

The README's usage example uses the mpg dataset that ships with the package, mapping engine displacement to the x axis, highway miles per gallon to the y axis, and car class to colour.

library(ggplot2)

ggplot(mpg, aes(displ, hwy, colour = class)) +
  geom_point()

What you should see is a scatterplot of 234 cars in seven colours, one per class, with displacement and highway mileage inversely correlated. That is the whole loop: data, mapping, one geom. Everything else in ggplot2 is an addition to that expression.

Where ggplot2 is the wrong tool

The README is unusually direct about the project's own pace. It notes that ggplot2 is used by hundreds of thousands of people to make millions of plots, and that as a result "ggplot2 itself changes relatively little." New functions and arguments are the preferred form of change; existing behaviour is altered only for what the README calls compelling reasons. If you need a plotting library that moves quickly, this is not it, and the README says so by pointing elsewhere: "If you are looking for innovation, look to ggplot2's rich ecosystem of extensions."

That has a concrete cost. A geom you want may not exist in the core package, and the answer is a third-party extension with its own maintenance schedule and its own compatibility window against the ggplot2 version you have installed. The core package's stability does not transfer to the extensions.

The other clear boundary is the language. Everything here is R. The repository is R source under R/, with man/ pages, vignettes/, and an R package DESCRIPTION. A search for ggplot2 in Python is about a different library that imitates the API, not about this repository, and the README offers no Python path. Teams that need one plotting stack across R and Python services will be maintaining two grammars that only look alike.

A quieter limitation is the object model itself. Because a plot is a description, debugging a plot that renders wrongly means inspecting the built object rather than stepping through drawing calls. The documentation for that inspection lives in the package's man pages and vignettes, not in the README.

ggplot2 versus base R graphics

The honest alternative for an R user is base graphics. The difference is not cosmetic. Base graphics is imperative and stateful: each call draws onto the current device, and the order of calls determines what is on top. There is no plot object to save, modify, or hand to another function, and no automatic legend or axis assembly from a data mapping.

ggplot2 is declarative and value-based. The plot is an object, layers are added to it, and scales generate axes and legends from the mappings that are present. Facets, which base graphics handles by manually setting up a panel grid with par(mfrow = ...), are a one-line addition in ggplot2.

Base graphics wins in two places. It has no dependency footprint beyond R itself, which matters in constrained environments. And for a single throwaway plot, the imperative version is shorter, because there is no grammar to set up. The trade is that the throwaway plot is harder to reuse, and reuse is the case ggplot2 was built for.

Version 4.0.3, the NEWS file, and what upgrading costs

The most recent release listed for the repository is v4.0.3, dated 2026-04-22, following v4.0.2 in February 2026 and v4.0.1 in November 2025. The last push to the default branch was on 2026-09-17. The repository is not archived.

The README states the upgrade policy plainly: changes are generally additions of new functions or arguments, and behaviour changes to existing functions happen only for compelling reasons. That policy is the reason a major version can land without a rewrite of every script, and it is also why reading NEWS before upgrading is worth the two minutes. Additions do not break code; the behaviour changes are the ones that alter an existing plot's output, and they are the entries to look for.

The extension ecosystem is where upgrade cost actually lives. A package that extends ggplot2's internals can break on a ggplot2 release even when the release only added arguments, because it was reaching into parts of the object model that the core package does not promise to keep fixed. If your reporting stack depends on several extensions, the ggplot2 version is not the only thing to pin.

On licensing, the repository carries LICENSE and LICENSE.md files at the top level, and the metadata reports the licence as NOASSERTION, meaning the automated classifier could not map it to a standard identifier. Read both files before redistributing the package or bundling it into a product. This is a description of what the repository contains, not legal advice.

Editorial conclusion

Adopt ggplot2 if you work in R and want plots described as data mappings plus layers, because the API is stable and the extension ecosystem is where new geoms and themes live. Do not adopt it as a Python plotting library: the README and repository are R only, and the searches asking how to use ggplot2 in Python point at a different tool than this package. Before committing, check the installed version against the v4.0.3 release notes and read the NEWS file for behaviour changes, and confirm your reporting pipeline can render the plots outside an interactive session.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. tidyverse/ggplot2 on GitHub