2 Getting Started

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!