[ RDocumentation ](/)

Moon  [ ](https://github.com/datacamp/rdocumentation-2.0) [ Learn R
](https://www.datacamp.com/learn/r)

Search all packages and functions

[ base  (version  3.6.2  ) ](/packages/base/versions/3.6.2)

#  ns-hooks: Hooks for Namespace Events

##  Description

Packages can supply functions to be called when loaded, attached, detached or
unloaded.

##  Usage

    
    
    .onLoad(libname, pkgname)
    .onAttach(libname, pkgname)
    .onUnload(libpath)
    .onDetach(libpath)
    .Last.lib(libpath)

##  Arguments

libname

a character string giving the library directory where the package defining the
namespace was found.

pkgname

a character string giving the name of the package.

libpath

a character string giving the complete path to the package.

##  Good practice

Loading a namespace should where possible be silent, with startup messages
given by ` .onAttach ` . These messages (and any essential ones from ` .onLoad
` ) should use ` [ packageStartupMessage
](/link/packageStartupMessage?package=base&version=3.6.2) ` so they can be
silenced where they would be a distraction.

There should be no calls to ` library ` nor ` require ` in these hooks. The
way for a package to load other packages is via the  Depends  field in the `
DESCRIPTION ` file: this ensures that the dependence is documented and
packages are loaded in the correct order. Loading a namespace should not
change the search path, so rather than attach a package, dependence of a
namespace on another package should be achieved by (selectively) importing
from the other package's namespace.

Uses of ` library ` with argument ` help ` to display basic information about
the package should use ` format ` on the computed package information object
and pass this to ` packageStartupMessage ` .

There should be no calls to ` [ installed.packages
](/link/installed.packages?package=base&version=3.6.2) ` in startup code: it
is potentially very slow and may fail in versions of  R  before 2.14.2 if
package installation is going on in parallel. See its help page for
alternatives.

Compiled code should be loaded (e.g., _via_ ` [ library.dynam
](/link/library.dynam?package=base&version=3.6.2) ` ) in ` .onLoad ` or a `
useDynLib ` directive in the ` NAMESPACE ` file, and not in ` .onAttach ` .
Similarly, compiled code should not be unloaded (e.g., _via_ ` [
library.dynam.unload ](/link/library.dynam.unload?package=base&version=3.6.2)
` ) in ` .Last.lib ` nor ` .onDetach ` , only in ` .onUnload ` .

##  Details

After loading, ` [ loadNamespace
](/link/loadNamespace?package=base&version=3.6.2) ` looks for a hook function
named ` .onLoad ` and calls it (with two unnamed arguments) before sealing the
namespace and processing exports.

When the package is attached (via ` [ library
](/link/library?package=base&version=3.6.2) ` or ` [ attachNamespace
](/link/attachNamespace?package=base&version=3.6.2) ` ), the hook function `
.onAttach ` is looked for and if found is called (with two unnamed arguments)
before the package environment is sealed.

If a function ` .onDetach ` is in the namespace or ` .Last.lib ` is exported
from the package, it will be called (with a single argument) when the package
is ` [ detach ](/link/detach?package=base&version=3.6.2) ` ed. Beware that it
might be called if ` .onAttach ` has failed, so it should be written
defensively. (It is called within ` [ tryCatch
](/link/tryCatch?package=base&version=3.6.2) ` , so errors will not stop the
package being detached.)

If a namespace is unloaded (via ` [ unloadNamespace
](/link/unloadNamespace?package=base&version=3.6.2) ` ), a hook function `
.onUnload ` is run (with a single argument) before final unloading.

Note that the code in ` .onLoad ` and ` .onUnload ` should not assume any
package except the base package is on the search path. Objects in the current
package will be visible (unless this is circumvented), but objects from other
packages should be imported or the double colon operator should be