What is the difference between require() and library()?

Asked 8/4, 2011 at 13:9 Answered 10/7, 2018 at 11:0

668

What is the difference between require() and library()?

Asthma answered 8/4, 2011 at 13:9 Comment(6)

mail-archive.com/[email protected]/msg00301.html – Lance 8/4, 2011 at 13:13

Adding a link to @Yihui's blog post unless he wants to post a version of it as an answer. yihui.name/en/2014/07/library-vs-require – Spinster 3/2, 2016 at 21:13

I usually use require if I want a logical value returned after package loading. – Foulmouthed 15/12, 2016 at 9:43

Summarizing @Yihui's blog post: "Ladies and gentlemen, I've said this before: require() is the wrong way to load an R package; use library() instead " – Cotten 21/3, 2018 at 3:32

@DanHall ... because library() immediately fails loudly, early, and with a relevant error message (if the package is not installed or could not be loaded), whereas require() doesn't raise an error, just silently returns boolean FALSE which gets thrown away, and causes the code to fail later and more cryptically with Error: object “bar” not found on (say) line 175. – Blamable 27/6, 2018 at 2:59

Hi @Marco, this question is fairly popular and is getting lots of traffic. Unfortunately the accepted answer is (completely) wrong in that it contradicts commonly accepted best practices, as explained in the comments and by other answers, and is misinforming people. Would you mind considering the other answers and accepting one that provides a correct explanation? (Given that I’m the one supplicating you, I suggest accepting dww’s answer, which I’ve upvoted. It’s the only answer apart from mine that points out the serious caveats of using require.) – Peursem 10/10, 2019 at 18:8

143

In addition to the good advice already given, I would add this:

It is probably best to avoid using require() unless you actually will be using the value it returns e.g in some error checking loop such as given by thierry.

In most other cases it is better to use library(), because this will give an error message at package loading time if the package is not available. require() will just fail without an error if the package is not there. This is the best time to find out if the package needs to be installed (or perhaps doesn't even exist because it it spelled wrong). Getting error feedback early and at the relevant time will avoid possible headaches with tracking down why later code fails when it attempts to use library routines

Unnecessary answered 10/2, 2015 at 1:24 Comment(0)

386

There's not much of one in everyday work.

However, according to the documentation for both functions (accessed by putting a ? before the function name and hitting enter), require is used inside functions, as it outputs a warning and continues if the package is not found, whereas library will throw an error.

Bellringer answered 8/4, 2011 at 13:14 Comment(4)

#richiemorrisroe: Thank you. Does it mean that if I load the packages I need at the very beginning of my R-code it does not matter which one I choose? – Asthma 8/4, 2011 at 13:20

as long as you are not loading packages inside a function, it really makes no difference. I load all my packages using require, and didnt know what the difference was until i read the help after seeing your question. – Bellringer 8/4, 2011 at 13:43

The other reason I use require is that it keeps me from referring to packages as libraries, a practice that drives the R-cognoscenti up the wall. The library is the directory location where the packages sit. – Runthrough 8/4, 2011 at 15:53

They have very relevant differences. Do not use require, unless you check the return value (and in that case there are usually better alternatives, e.g. loadNamespace). – Peursem 28/9, 2015 at 10:2

278

Another benefit of require() is that it returns a logical value by default. TRUE if the packages is loaded, FALSE if it isn't.

> test <- library("abc")
Error in library("abc") : there is no package called 'abc'
> test
Error: object 'test' not found
> test <- require("abc")
Loading required package: abc
Warning message:
In library(package, lib.loc = lib.loc, character.only = TRUE, logical.return = TRUE,  :
  there is no package called 'abc'
> test
[1] FALSE

So you can use require() in constructions like the one below. Which mainly handy if you want to distribute your code to our R installation were packages might not be installed.

if(require("lme4")){
    print("lme4 is loaded correctly")
} else {
    print("trying to install lme4")
    install.packages("lme4")
    if(require(lme4)){
        print("lme4 installed and loaded")
    } else {
        stop("could not install lme4")
    }
}

Fijian answered 8/4, 2011 at 21:52 Comment(0)

143

In addition to the good advice already given, I would add this:

It is probably best to avoid using require() unless you actually will be using the value it returns e.g in some error checking loop such as given by thierry.

Unnecessary answered 10/2, 2015 at 1:24 Comment(0)

Always use `library`. Never use `require`.

tl;dr: require breaks one of the fundamental rules of robust software systems: fail early.

In a nutshell, this is because, when using require, your code might yield different, erroneous results, without signalling an error. This is rare but not hypothetical! Consider this code, which yields different results depending on whether {dplyr} can be loaded:

require(dplyr)

x = data.frame(y = seq(100))
y = 1
filter(x, y == 1)

This can lead to subtly wrong results. Using library instead of require throws an error here, signalling clearly that something is wrong. This is good.

It also makes debugging all other failures more difficult: If you require a package at the start of your script and use its exports in line 500, you’ll get an error message “object ‘foo’ not found” in line 500, rather than an error “there is no package called ‘bla’”.

The only acceptable use case of require is when its return value is immediately checked, as some of the other answers show. This is a fairly common pattern but even in these cases it is better (and recommended, see below) to instead separate the existence check and the loading of the package. That is: use requireNamespace instead of require in these cases.

More technically, require actually calls library internally (if the package wasn’t already attached — require thus performs a redundant check, because library also checks whether the package was already loaded). Here’s a simplified implementation of require to illustrate what it does:

require = function (package) {
    already_attached = paste('package:', package) %in% search()
    if (already_attached) return(TRUE)
    maybe_error = try(library(package, character.only = TRUE)) 
    success = ! inherits(maybe_error, 'try-error')
    if (! success) cat("Failed")
    success
}

Experienced R developers agree:

Yihui Xie, author of {knitr}, {bookdown} and many other packages says:

Ladies and gentlemen, I've said this before: require() is the wrong way to load an R package; use library() instead

Hadley Wickham, author of more popular R packages than anybody else, says

Use library(x) in data analysis scripts. […] You never need to use require() (requireNamespace() is almost always better)

Peursem answered 10/7, 2018 at 11:0 Comment(1)

I was gonna point exactly the same, unless you are calling ALL the functions with the syntax class::function, use library() to avoid precisely that. – Williswillison 10/10, 2019 at 17:55

You can use require() if you want to install packages if and only if necessary, such as:

if (!require(package, character.only=T, quietly=T)) {
    install.packages(package)
    library(package, character.only=T)
}

For multiple packages you can use

for (package in c('<package1>', '<package2>')) {
    if (!require(package, character.only=T, quietly=T)) {
        install.packages(package)
        library(package, character.only=T)
    }
}

Pro tips:

When used inside the script, you can avoid a dialog screen by specifying the repos parameter of install.packages(), such as
```
install.packages(package, repos="http://cran.us.r-project.org")
```
You can wrap require() and library() in suppressPackageStartupMessages() to, well, suppress package startup messages, and also use the parameters require(..., quietly=T, warn.conflicts=F) if needed to keep the installs quiet.

Relay answered 20/8, 2014 at 15:57 Comment(0)

?library

and you will see:

library(package) and require(package) both load the package with name package and put it on the search list. require is designed for use inside other functions; it returns FALSE and gives a warning (rather than an error as library() does by default) if the package does not exist. Both functions check and update the list of currently loaded packages and do not reload a package which is already loaded. (If you want to reload such a package, call detach(unload = TRUE) or unloadNamespace first.) If you want to load a package without putting it on the search list, use requireNamespace.

Nicolais answered 15/12, 2013 at 15:41 Comment(0)

My initial theory about the difference was that library loads the packages whether it is already loaded or not, i.e. it might reload an already loaded package, while require just checks that it is loaded, or loads it if it isn't (thus the use in functions that rely on a certain package). The documentation refutes this, however, and explicitly states that neither function will reload an already loaded package.

Bertrambertrand answered 9/10, 2013 at 15:35 Comment(2)

this is interesting, but isn't really an answer to the question ... ? – Fourier 8/5, 2014 at 18:6

This answer is being discussed on meta. – Nobles 17/7, 2019 at 11:14

Here seems to be the difference on an already loaded package. While it is true that both require and library do not load the package. Library does a lot of other things before it checks and exits.

I would recommend removing "require" from the beginning of a function running 2mil times anyway, but if, for some reason I needed to keep it. require is technically a faster check.

microbenchmark(req = require(microbenchmark), lib = library(microbenchmark),times = 100000)
Unit: microseconds
 expr    min     lq      mean median     uq        max neval
  req  3.676  5.181  6.596968  5.655  6.177   9456.006 1e+05
  lib 17.192 19.887 27.302907 20.852 22.490 255665.881 1e+05

Vicinity answered 22/2, 2016 at 14:34 Comment(3)

I’d argue that this is a strong reason for fixing the implementation library instead (both functions, as currently shipped with R, are a huge mess). – Peursem 10/7, 2018 at 11:8

@KonradRudolph well, if someone is going to fix library, maybe they can also enable loading by version explicitly and make attachment an argument option – Vicinity 10/7, 2018 at 20:16

Yes, I absolutely agree but those would change the semantics, not just the performance. Anyway, versioning will never work with packages in R, unfortunately. I’m working on a replacement for this (really!). As for attaching, you can use loadNamespace, which loads a package and returns its namespace, without attaching it. – Peursem 11/7, 2018 at 9:24

Hot tags

Godot Unity Godot Help Programming Godot 4.X GUI GDScript 3D 2D Physics CSharp Godot 3.X VR XR Projects C++

Always use library. Never use require.

Experienced R developers agree:

Recommended topics

Hot tags

Always use `library`. Never use `require`.