use-package User Manual
The use-package
macro allows you to set up package
customization in your init file in a declarative way. It takes care
of many things for you that would otherwise require a lot of
repetitive boilerplate code. It can help with common customization,
such as binding keys, setting up hooks, customizing user options and
faces, autoloading, and more. It also helps you keep Emacs startup
fast, even when you use many (even hundreds) of packages.
Note that use-package is not a package manager. Although use-package does have the useful capability to interface with the Emacs package manager, its primary purpose is help with the configuration and loading of packages, not with managing their download, upgrades, and installation.
This manual is for use-package 2.4.5 as distributed with Emacs 29.1.90.
Copyright © 2022–2024 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual”, and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License”.
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual.”
Table of Contents
- 1 Basic Concepts
- 2 Getting Started
- 3 Loading Packages
- 4 Configuring Packages
- 5 Installing packages automatically
- 6 Byte-compiling your init file
- 7 Troubleshooting
- Appendix A Keyword extensions
- Appendix B History and acknowledgments
- Appendix C GNU Free Documentation License
- Index
Next: Getting Started, Previous: use-package User Manual, Up: use-package User Manual [Contents][Index]
1 Basic Concepts
use-package provides the use-package
macro, that simplifies the
customization and use of packages in Emacs. It was created for a few
basic reasons, each of which drove the design. Understanding these
reasons may help make some of those decisions clearer:
- Allow gathering all the configuration details of a package into one place, making it easier to copy, disable, or move it elsewhere in the init file.
- Reduce duplication and repetitive boilerplate, capturing several common practices as mere keywords both easy and intuitive to use.
- Make startup time of Emacs as short as possible, without sacrificing the quantity of add-on packages used.
- Ensure that errors encountered during startup disable only the package(s) raising the error(s), and as little else as possible, leaving Emacs as close to fully functional as possible.
- Allow byte-compiling your init file, so that any warnings or errors you see at startup are meaningful. In this way, even if byte-compilation is not used for speed (see item 3 above), it can still be used as a sanity check.
It is worth noting that use-package is not intended to replace the standard customization command M-x customize (see Easy Customization in GNU Emacs Manual). On the contrary, it is designed to work together with it, for things that Customize cannot do.
Next: Loading Packages, Previous: Basic Concepts, Up: use-package User Manual [Contents][Index]
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!
Next: Configuring Packages, Previous: Getting Started, Up: use-package User Manual [Contents][Index]
3 Loading Packages
Before use-package can load an Emacs Lisp package, it must be
available in a directory on your load-path
. When you install
packages using the built-in install-package
command, it will do
this automatically for you. Packages shipped with Emacs (built-in
packages) are always available.
Some packages have more than one library. In those cases, you might
need more than one use-package
declaration to make sure the
package is properly loaded. For complex configurations, you might
also need more than one declaration for a package with the same name.
use-package can interface with ‘package.el’ to install packages on Emacs start. See Installing packages automatically, for details.
- How and when use-package loads packages
- Deferring package loading
- Forcing package to load immediately
- Loading packages conditionally
- Loading packages in sequence
- Prevent loading if dependencies are missing
- Manually installed package
Next: Deferring package loading, Up: Loading Packages [Contents][Index]
3.1 How and when use-package loads packages
The call to the use-package
macro will load a package either
immediately, or when the package is first used (via autoloading). In the
simplest case, a use-package
declaration loads a package when
it is evaluated.1 If the declaration is in your
init file, this happens automatically each time Emacs is started.
For example, the declaration below immediately loads the library
foo
, just like require
would:
(use-package foo)
If the library ‘foo’ is not available in your load-path
,
the declaration logs a warning to the ‘*Messages*’ buffer.
Note that a “package” is different from an Emacs Lisp “library”.
The above declaration tells use-package to load the library
foo.el, which in the overwhelming majority of cases also
resides in a package named foo
. But the package
foo
might also contain a library named foo-extra.el. If
that library is not loaded automatically, you will need a separate
use-package
declaration to make sure that it is loaded when
needed. This manual will often use the terms “package” and
“library” interchangeably, as this distinction does not usually
matter, but you should keep it in mind for the cases when it does.
The details of how and when you should load a package might differ from one package to another. When in doubt, refer to the package documentation for details.
Next: Forcing package to load immediately, Previous: How and when use-package loads packages, Up: Loading Packages [Contents][Index]
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).
Next: Loading packages conditionally, Previous: Deferring package loading, Up: Loading Packages [Contents][Index]
3.3 Forcing package to load immediately
The presence of autoloading trigger keywords can be overridden using
:demand t
, which forces the package to load immediately. Thus,
even if you use an autoloading keyword such as :bind
(see Key bindings), adding :demand
will force loading to
occur immediately. It will also avoid creating an autoload for the
bound key, as it would be redundant.
If you specify both :demand t
and :defer t
, the
:defer
keyword will take precedence.
Next: Loading packages in sequence, Previous: Forcing package to load immediately, Up: Loading Packages [Contents][Index]
3.4 Loading packages conditionally
The :if
, :when
, and :unless
keywords predicates
the loading and initialization of packages. They all accept one
argument, an Emacs Lisp form that is evaluated at run-time.
If the argument of the :if
keyword evaluates to non-nil
,
the package will be loaded and initialized. The :when
keyword
is provided as an alias for :if
. Finally, the :unless
keyword is the inverse of :if
, such that :unless foo
means the same thing as :if (not foo)
.
For example, if you only want to load ‘foo’ in graphical Emacs sessions, you could use the following:
(use-package foo :if (display-graphic-p))
Some common use cases
Here are some common cases for conditional loading, and how to achieve them.
Jump to: | :
A B C D E F G H I K L M N O P Q R S T U V |
---|
Jump to: | :
A B C D E F G H I K L M N O P Q R S T U V |
---|
Footnotes
(1)
This happens both at run-time and at compile-time. See Byte-compiling your init file.
(2)
When in doubt, you might as well use diminish.
(3)
The diminish package is installable from GNU ELPA.
(4)
The delight package is installable from GNU ELPA.
(5)
The :pin
keyword has no effect on
Emacs versions older than 24.4.
(6)
On macOS, your exec-path
might be
different if you are starting Emacs as a GUI app instead of from a
shell. If you find that Emacs on macOS cannot find some executables
that you know are already installed, you could try the
‘exec-path-from-shell’
package.
(7)
For
manual testing, you could use the executable-find
function,
which is what ‘system-packages’ uses internally.