3.2 Deferring package loading

In the examples we have seen so far, use-package loads packages every time you start Emacs, even if that package is never used. That will make starting Emacs slower. use-package therefore allows setting things up in such a way that packages are only loaded when some of the package’s commands is first used (either with M-x or via some key binding). This is based on autoloading, a full description of which is outside the scope of this manual. See Autoload in GNU Emacs Lisp Reference Manual, for the full story.

Some use-package keywords provide autoload triggers that cause a package to be loaded when certain events occur. For example, the :hook keyword sets up a trigger that fires when the specified hook is run, and then loads the package automatically. The other trigger keywords, all of which are described later in this manual, are :commands, :bind, :bind*, :bind-keymap, :bind-keymap*, :mode, and :interpreter.

The :defer keyword

If you did not specify any autoloading keyword, use-package will fall back to loading the package immediately (typically when Emacs is starting up). This can be overridden using the :defer keyword. It takes one boolean argument: a non-nil value means to stop this package from being immediately loaded. Here is an example of using :defer to postpone loading the package ‘foo’:

(use-package foo
  :defer t)

Using :defer t by itself like this is rarely useful. Typically, you would only use it together with a keyword like :config (see Using Lisp code for configuring packages), or :ensure (see Installing packages automatically).

Defer loading until idle for N seconds

You can also give a numeric argument n to :defer to specify that a package should be loaded (if it hasn’t already) after Emacs has been idle for n seconds. For example, use the following to make use-package load ‘foo’ after 30 seconds of idle time:

(use-package foo
  :defer 30)

When to use :defer

When using autoloading keywords, there is no need to also use :defer. It doesn’t hurt to add it in this case, perhaps for extra clarity, but it is redundant.

You should use :defer to force deferred loading, in cases when use-package isn’t creating any autoloads for you. For example, you might know that some other package will already do something to cause your package to load at the appropriate time. This is usually the case when you install a package using package-install, as packages installed in this way normally always have their own autoloads already set up.

Making :defer t the default

If you customize the user option use-package-always-defer to non-nil, the use-package macro will behave as if :defer t is always specified. This can be overridden for individual declarations using either :defer nil or :demand t (see Forcing package to load immediately).