This chapter provides instructions and examples for quickly getting
started with use-package. In this manual, we say that each call to
the use-package
macro in your init file is a declaration,
to highlight the declarative nature of its syntax.
To unconditionally load a package named ‘foo’, add the following declaration to your init file:
(use-package foo)
This declaration is equivalent to using require
(see Named
Features in GNU Emacs Lisp Reference Manual), with some
use-package specific error handling added in. Just like
require
, it needs the package ‘foo’ to be installed and
available via your load-path
(see Installing packages automatically).
To evaluate some Lisp before the ‘foo’ package is loaded,
use the :init
keyword:
(use-package foo :init (setq foo-variable t))
Similarly, :config
can be used to execute code after a
package is loaded. In cases where loading is done lazily
(see Loading Packages), this execution is deferred until after the
loading actually occurs. As you might expect, you can use
:init
and :config
together:
(use-package foo :init (setq foo-variable t) :config (foo-mode 1))
The above declarations will load the ‘foo’ package immediately. In most cases, this is not necessary or desirable, as that will slow down Emacs startup. Instead, you should try to set things up so that packages are only loaded when they are actually needed (a.k.a. “autoloading”). If you have installed a package from GNU ELPA that provides it’s own autoloads, it is often enough to say:
(use-package foo :defer t)
This will avoid loading the package. Now, when you run any autoloaded command, the package ‘foo’ is loaded automatically. (Which commands from a package are marked to auto-load by default is the decision of the package authors.)
In some cases, you might need or want to provide your own autoloads.
The more complex example below autoloads the commands
isearch-moccur
and isearch-all
from the package
color-moccur.el, and binds keys both globally and in
isearch-mode-map
. When one of these two commands are used, the
package will be loaded. At that point, moccur-edit
is also loaded,
to allow editing of the moccur
buffer.
(use-package color-moccur :commands (isearch-moccur isearch-all) :bind (("M-s O" . moccur) :map isearch-mode-map ("M-o" . isearch-moccur) ("M-O" . isearch-moccur-all)) :init (setq isearch-lazy-highlight t) :config (use-package moccur-edit))
Some packages will suggest ready-made use-package
declarations
that you can use. Where possible, it is a good idea to copy them, and
use that as a starting point.
That should be enough to get you started!