library

R Base 3.6.2

library and require load and attach add-on packages.

Syntax

library(package, help, pos = 2, lib.loc = NULL,
        character.only = FALSE, logical.return = FALSE,
        warn.conflicts, quietly = FALSE,
        verbose = getOption("verbose"),
        mask.ok, exclude, include.only,
        attach.required = missing(include.only))<p></p><p>require(package, lib.loc = NULL, quietly = FALSE,
        warn.conflicts,
        character.only = FALSE,
        mask.ok, exclude, include.only,
        attach.required = missing(include.only))</p><p>conflictRules(pkg, mask.ok = NULL, exclude = NULL)</p>

Arguments

Parameter	Description
`package, help`	the name of a package, given as a name or literal character string, or a character string, depending on whether character.only is FALSE (default) or TRUE.
`pos`	the position on the search list at which to attach the loaded namespace. Can also be the name of a position on the current search list as given by search().
`lib.loc`	a character vector describing the location of R library trees to search through, or NULL. The default value of NULL corresponds to all libraries currently known to .libPaths(). Non-existent library trees are silently ignored.
`character.only`	a logical indicating whether package or help can be assumed to be character strings.
`logical.return`	logical. If it is TRUE, FALSE or TRUE is returned to indicate success.
`warn.conflicts`	logical. If TRUE, warnings are printed about conflicts from attaching the new package. A conflict is a function masking a function, or a non-function masking a non-function. The default is TRUE unless specified as FALSE in the conflicts.policy option.
`verbose`	a logical. If TRUE, additional diagnostics are printed.
`quietly`	a logical. If TRUE, no message confirming package attaching is printed, and most often, no errors/warnings are printed if package attaching fails.
`pkg`	character string naming a package.
`mask.ok`	character vector of names of objects that can mask objects on the search path without signaling an error when strict conflict checking is enabled
`exclude,include.only`	character vector of names of objects to exclude or include in the attached frame. Only one of these arguments may be used in a call to library or require.
`attach.required`	logical specifying whether required packages listed in the Depends clause of the DESCRIPTION file should be attached automatically.

Return Value

Normally library returns (invisibly) the list of attached packages, but TRUE or FALSE if logical.return is TRUE. When called as library() it returns an object of class "libraryIQR", and for library(help=), one of class "packageInfo". require returns (invisibly) a logical indicating whether the required package is available.

Details

library(package) and require(package) both load the namespace of the package with name package and attach 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 attached packages and do not reload a namespace 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 attaching it on the search list, see requireNamespace. To suppress messages during the loading of packages use suppressPackageStartupMessages: this will suppress all messages from R itself but not necessarily all those from package authors.

Examples

Example

# NOT RUN {
library()                   # list all available packages
library(lib.loc = .Library) # list all packages in the default library
# }
# NOT RUN {
library(help = splines)     # documentation on package 'splines'
# }
# NOT RUN {
library(splines)            # attach package 'splines'
require(splines)            # the same
search()                    # "splines", too
detach("package:splines")

# if the package name is in a character vector, use
pkg <- "splines"
library(pkg, character.only = TRUE)
detach(pos = match(paste("package", pkg, sep = ":"), search()))

require(pkg, character.only = TRUE)
detach(pos = match(paste("package", pkg, sep = ":"), search()))

require(nonexistent)        # FALSE
# }
# NOT RUN {
## if you want to mask as little as possible, use
library(mypkg, pos = "package:base")
# }