Skip to content
An implementation of the Grammar of Graphics in R
Branch: master
Clone or download
Latest commit 23e3241 Sep 3, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Move to the main directory (#2973) Nov 2, 2018
R Clarify documentation in mpg: very minor (#3515) Sep 3, 2019
data-raw Update economics data (#2962) Mar 6, 2019
data Update economics data (#2962) Mar 6, 2019
icons Tweak icons May 9, 2018
inst Correct url link in citation (#3077) Jan 19, 2019
man Clarify documentation in mpg: very minor (#3515) Sep 3, 2019
pkgdown/favicon Use retina logo and generate favicons Nov 13, 2018
revdep revdeps (#3352) Jun 11, 2019
tests Make plot title position configurable. (#3494) Aug 27, 2019
vignettes Merge branch 'master' into v3.2.0-rc Jun 17, 2019
.Rbuildignore Update Jun 11, 2019
.gitattributes Avoid merge conflicts in NEWS file Feb 25, 2014
.gitignore Ignore docs dir Jan 5, 2019
.travis.yml Cleanup Travis config (#3354) Jul 24, 2019 Move to the main directory (#2973) Nov 2, 2018 Fixed broken link to (#3288) Jun 4, 2019
DESCRIPTION Remove lazyeval (#3495) Aug 24, 2019 Add Hiroaki Yutani to authors (#2976) Nov 2, 2018 Updates link to reprex how-to in issues template (#2385) Jan 2, 2018
LICENSE Make GPL-2 license explicit Sep 15, 2016
NAMESPACE Adds american spelling to `scale_colour_date/datetime()` (#3510) Aug 30, 2019
NEWS Standardise spelling: ‘faceting’ instead of ‘facetting’ (#2413) Jan 21, 2018 Add setup_params method to Geom (#3509) Aug 29, 2019
README.Rmd Edit README resource. (#3229) Apr 10, 2019 Edit README resource. (#3229) Apr 10, 2019
_pkgdown.yml Consolidate coordinate scale expansion and limiting code (#3380) Jul 1, 2019
appveyor.yml Use vdiffr for visual unit tests (#1874) Feb 1, 2017
codecov.yml Suppress codecov comments Jul 28, 2016 update cran comments Aug 9, 2019
ggplot2.Rproj Upgrade RStudio Jun 1, 2017


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)) + 



ggplot2 is now over 10 years old and is used by hundreds of thousands of people to make millions of plots. That means, by-and-large, ggplot2 itself changes relatively little. When we do make changes, they will be generally to add new functions or arguments rather than changing the behaviour of existing functions, and if we do make changes to existing behaviour we will do them for compelling reasons.

If you are looking for innovation, look to ggplot2’s rich ecosystem of extensions. See a community maintained 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 get you up to speed with the essentials of ggplot2 as quickly as possible.

  2. If you’d like to take an online course, try Data Visualization in R With ggplot2 by Kara Woo.

  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.

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 graphics 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 RStudio community is a friendly place to ask any questions about ggplot2.

  2. Stack Overflow 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.

You can’t perform that action at this time.