R: Loading and Listing of Packages

library {base} | R Documentation

## Loading and Listing of Packages

### Description

`library` and `require` load add-on packages.

### Usage

    library(package, help, pos = 2, lib.loc = NULL,
            character.only = FALSE, logical.return = FALSE,
            warn.conflicts = TRUE, quietly = FALSE,
            keep.source = getOption("keep.source.pkgs"),
            verbose = getOption("verbose"))

    require(package, lib.loc = NULL, quietly = FALSE,
            warn.conflicts = TRUE,
            keep.source = getOption("keep.source.pkgs"),
            character.only = FALSE)

### Arguments

`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 package. 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.
`keep.source` | logical. Now ignored. This argument does not apply to packages using lazy-loading: whether they have kept source is determined when they are installed.
`verbose` | a logical. If `TRUE`, additional diagnostics are printed.
`quietly` | a logical. If `TRUE`, no message confirming package loading is printed, and most often, no errors/warnings are printed if package loading fails.

### Details

`library(package)` and `require(package)` both load the package with name `package`. `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. (Furthermore, if the package has a namespace and a name space of that name is already loaded, they work from the existing namespace rather than reloading from the file system. If you want to reload such a package, call `detach(unload = TRUE)` or `unloadNamespace` first.)

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.

If `library` is called with no `package` or `help` argument, it lists all available packages in the libraries specified by `lib.loc`, and returns the corresponding information in an object of class `"libraryIQR"`. The structure of this class may change in future versions. In earlier versions of R, only the names of all available packages were returned; use `.packages(all = TRUE)` for obtaining these. Note that `installed.packages()` returns even more information.

`library(help = somename)` computes basic information about the package `somename`, and returns this in an object of class `"packageInfo"`. The structure of this class may change in future versions. When used with the default value (`NULL`) for `lib.loc`, the attached packages are searched before the libraries.

In versions of R prior to 2.14.0, a `.First.lib` function would be called when a package without a namespace was attached. As of 2.14.0, all functions have namespaces; see `.onLoad` for current behaviour, and ‘Writing R Extensions’ for a description of the older mechanism.

### 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.

### Licenses

Some packages have restrictive licenses, and there is a mechanism to allow users to be aware of such licenses. If `getOption("checkPackageLicense") == TRUE`, then at first use of a package with a not-known-to-be-FOSS (see below) license the user is asked to view and accept the license: a list of accepted licenses is stored in file ‘~/.R/licensed’. In a non-interactive session it is an error to use such a package whose license has not already been accepted.

Free or Open Source Software (FOSS, e.g., http://en.wikipedia.org/wiki/FOSS) packages are determined by the same filters used by `available.packages` but applied to just the current package, not its dependencies.

There can also be a site-wide file ‘R_HOME/etc/licensed.site’ of packages (one per line).

### Formal methods

`library` takes some further actions when package methods is attached (as it is by default). Packages may define formal generic functions as well as re-defining functions in other packages (notably base) to be generic, and this information is cached whenever such a package is loaded after methods and re-defined functions (implicit generics) are excluded from the list of conflicts. The caching and check for conflicts require looking for a pattern of objects; the search may be avoided by defining an object `.noGenerics` (with any value) in the package. Naturally, if the package does have any such methods, this will prevent them from being used.

### Note

`library` and `require` can only load an installed package, and this is detected by having a ‘DESCRIPTION’ file containing a Built: field.

Under Unix-alikes, the code checks that the package was installed under a similar operating system as given by `R.version$platform` (the canonical name of the platform under which R was compiled), provided it contains compiled code. Packages which do not contain compiled code can be shared between Unix-alikes, but not to other OSes because of potential problems with line endings and OS-specific help files. If sub-architectures are used, the OS similarity is not checked since the OS used to build may differ (e.g. `i386-pc-linux-gnu` code can be built on an `x86_64-unknown-linux-gnu` OS).

The package name given to `library` and `require` must match the name given in the package's ‘DESCRIPTION’ file exactly, even on case-insensitive file systems such as are common on MS Windows and Mac OS X.

### References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.

### See Also

`.libPaths`, `.packages`.

`attach`, `detach`, `search`, `objects`, `autoload`, `library.dynam`, `data`, `install.packages` and `installed.packages`; `INSTALL`, `REMOVE`.

The initial set of packages attached is set by `options(defaultPackages=)`: see also `Startup`.

### Examples

    library()                   # list all available packages
    library(lib.loc = .Library) # list all packages in the default library
    library(help = splines)     # documentation on package 'splines'
    library(splines)            # load 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")

    ## End(Not run)

[Package base version 2.15.1 Index]