Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Hole punch

R build status

Coveralls test coverage Lifecycle: maturing CRAN status

What this package does

holepunch will read the contents of your R project on GitHub, create a DESCRIPTION file with all dependencies, write a Dockerfile, add a badge to your README, and build a Docker image. Once these 4 steps are complete, any reader can click the badge and within minutes, be dropped into a free, live, RStudio server. Here they can run your scripts and notebooks and see how everything works.


Binder is an open source project that can take any most GitHub repos of notebooks (R or Jupyter) and turn them into a free, live instance that not only has all dependencies ready to go but also provides Jupyter or Rstudio server to run the code on. The instances are small and should not be used to demonstrate resource intensive computation. However they are ideal for reproducing papers/figures/examples and make a great addition to any public analysis project that is being hosted on GitHub.


Why this is awesome

  • You can launch a free instance of Rstudio server from any of your projects on GitHub. The instance will have all of your dependencies and version of R installed and ready to go!
  • Easily allow anyone (up to 100 simultaneous users) to replicate or modify your analysis
  • Free


  • The server has limited memory so you cannot load large datasets or run big computations
  • Binder is meant for interactive and ephemeral interactive coding so an instance will die after 10 minutes of inactivity.
  • An instance cannot be kept alive for more than 12 hours


# Please report any installation problems in the issues

Setting up your project as a compendium (recommended)

If you are unfamiliar with the idea of research compendia, I highly recommend reading this paper by Marwick et al:

Marwick B, Boettiger C, Mullen L. 2018. Packaging data analytical work reproducibly using R (and friends) PeerJ Preprints 6:e3192v2

and also looking through my presentation at RStudio::conf 2019 where I talk about this in detail.

write_compendium_description(package = "Your compendium name", 
                             description = "Your compendium description")
# to write a description, with dependencies. Be sure to fill in placeholder text

write_dockerfile(maintainer = "your_name") 
# To write a Dockerfile. It will automatically pick the date of the last 
# modified file, match it to that version of R and add it here. You can 
# override this by passing r_date to some arbitrary date
# (but one for which a R version exists).

generate_badge() # This generates a badge for your readme.

# ----------------------------------------------
# At this time πŸ™Œ push the code to GitHub πŸ™Œ
# ----------------------------------------------

# And click on the badge or use the function below to get the build 
# ready ahead of time.
# πŸ€žπŸš€

Alternate setup method

If for some reason you really don't want to set up your project as a compendium, then set it up by creating runtime.txt and install.R. This build will take a very long time.

# Note that this particular approach will be super slow.
# And take just as long everytime you edit your code
write_install() # Writes install.R with all your dependencies
write_runtime() # Writes the date your code was last modified. Can be overridden.
generate_badge() # Generates a badge you can add to your README. Clicking badge will launch the Binder.
# ----------------------------------------------
# At this time πŸ™Œ push the code to GitHub πŸ™Œ
# ----------------------------------------------
# Then click the badge on your README or run
build_binder() # to kick off the build process
# πŸ€žπŸš€

Testing this package

An easy way to test this package without writing any code is to visit the binder-test repo and follow the instructions.


The ETA for the first release of this package is fall 2019 (after renv goes to CRAN). Comments, suggestions for improving the workflow or any other comments welcome in the issues. Other planned features include:

  • Full support for GitHub packages
  • Support for Bioconductor packages
  • Reference Binders to separate environment from code (still in early planning)

Code of conduct

Please note that the 'holepunch' project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.


Make your R project Binder ready



Unknown, MIT licenses found

Licenses found


Code of conduct





No releases published

Sponsor this project



No packages published