An implementation of the Grammar of Graphics in R
Latest commit 73e77b6 Feb 14, 2017 @hadley hadley More issue template tweaking
* Move to top-level
* Add to Rbuildignore
Failed to load latest commit information.
R Pass R CMD check even when sf not installed Feb 13, 2017
data-raw Add new txhousing dataset Aug 20, 2015
data Add new txhousing dataset Aug 20, 2015
icons Tweak icons Nov 7, 2016
inst Update CITATION (#1984) Jan 24, 2017
man Pass R CMD check even when sf not installed Feb 13, 2017
revdep Prepare for submission Nov 8, 2016
tests Skip geom_sf in arg checking Feb 13, 2017
vignettes added note about renamed layer parameters (#2015) Jan 30, 2017
.Rbuildignore More issue template tweaking Feb 14, 2017
.gitattributes Avoid merge conflicts in NEWS file Feb 25, 2014
.gitignore Add inherit.blank argument to element constructors (#1754) Sep 21, 2016
.travis.yml Disable oldrel testing Feb 13, 2017 Turn development vignette into Jul 23, 2015
DESCRIPTION Pass R CMD check even when sf not installed Feb 13, 2017 More issue template tweaking Feb 14, 2017
LICENSE Make GPL-2 license explicit Sep 15, 2016
NAMESPACE Add support for sf (#1990) Feb 9, 2017
NEWS Specify alpha for outlier points in geom_boxplot. (#1644) Sep 15, 2016 Teach geom smooth about its optional aesthetics Feb 13, 2017
README-example-1.png Remove redundant word Jan 24, 2017
README.Rmd Add link to ggplot2 exts Jan 26, 2017 Add link to ggplot2 exts Jan 26, 2017
_pkgdown.yml Fix link Nov 2, 2016
appveyor.yml Use vdiffr for visual unit tests (#1874) Feb 1, 2017
codecov.yml Suppress codecov comments Jul 28, 2016 Prepare for patch release. Dec 30, 2016
ggplot2.Rproj Put --run-donttest in correct config Oct 6, 2016
logo.png Add logo Oct 31, 2016


Travis Build Status AppVeyor Build Status Coverage Status CRAN\_Status\_Badge


ggplot2 is a system for declaratively creating graphics, based on The Grammar of Graphics. 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 easiest way to get ggplot2 is to install the whole tidyverse:

# Alternatively, install just ggplot2:

# Or the the development version from GitHub:
# install.packages("devtools")


It's hard to succinctly describe how ggplot2 works because it embodies a deep philosophy of visualisation. However, in most cases you start with ggplot(), supply a dataset and aesthetic mapping (with aes()). You then add on layers (like geom_point() or geom_histogram()), scales (like scale_colour_brewer()), faceting specifications (like facet_wrap()) and coordinate systems (like coord_flip()).


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

As well as the components built-in to ggplot2, there are many packages that provide extensions. See a comphrensive list at

Learning ggplot2

If you are new to ggplot2 you are better off starting with a systematic introduction, rather than trying to learn from reading individual documentation pages. Currently, there are three good places to start:

  1. The data visualisation and graphics for communication chapters in R for data science. R for data science is designed to give you a comprehensive introduction to the tidyverse, and these two chapters will you get up to speed with the essentials of ggplot2 as quickly as possible.

  2. If you'd like to take an interactive online course, try Data visualisation with ggplot2 by Rick Scavetta on datacamp.

  3. If you want to dive into making common graphics as quickly as possible, I recommend The R Graphics Cookbook by Winston Chang. It provides a set of recipes to solve common graphics problems. A 2nd edition is due out in 2017.

If you've mastered the basics and want to learn more, read ggplot2: Elegant Graphics for Data Analysis. It describes the theoretical underpinnings of ggplot2 and shows you how all the pieces fit together. This book helps you understand the theory that underpins ggplot2, and will help you create new types of graphic specifically tailored to your needs. The book is not available for free, but you can find the complete source for the book at

Getting help

There are two main places to get help with ggplot2:

  1. The ggplot2 mailing list is a friendly place to ask any questions about ggplot2. You must be a member to post messages, but anyone can read the archived discussions.

  2. stackoverflow is a great source of answers to common ggplot2 questions. It is also a great place to get help, once you have created a reproducible example that illustrates your problem.