emacs/doc/misc/use-package.texi

\input texinfo    @c -*- texinfo -*-
@c %**start of header
@setfilename ../../info/use-package.info
@settitle use-package User Manual
@set USEP_VER 2.4.5
@set USEP_DIST as distributed with Emacs @value{EMACSVER}
@include docstyle.texi
@syncodeindex vr cp
@syncodeindex fn cp
@include emacsver.texi
@c %**end of header

@copying
This manual is for use-package @value{USEP_VER} @value{USEP_DIST}.

Copyright @copyright{} 2022--2024 Free Software Foundation, Inc.

@quotation
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.''
@end quotation
@end copying

@dircategory Emacs misc features
@direntry
* use-package: (use-package). Declarative package configuration for Emacs.
@end direntry

@finalout
@titlepage
@title use-package User Manual
@subtitle for version USEP_VER
@author John Wiegley & Stefan Kangas
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top use-package User Manual

The @code{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.

@insertcopying

@menu
* Basic Concepts::              Basic concepts of use-package.
* Getting Started::             A gentle introduction to use-package.
* Loading Packages::            How and when packages are loaded.
* Configuring Packages::        Package configuration keywords.
* Installing packages::         Ensuring packages are available.
* Byte-compiling::              Byte-compiling your init file.
* Troubleshooting::             What to do when there's trouble.

Appendices
* Keyword extensions::          Adding new use-package keywords.
* History::                     History and acknowledgments.
* GNU Free Documentation License::  The license for this manual.

Index
* Index::
@end menu
@end ifnottex

@c ----------------------------------------------------------------------------
@node Basic Concepts
@chapter Basic Concepts

use-package provides the @code{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:

@cindex reasons for developing use-package
@enumerate
@item
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.

@item
Reduce duplication and repetitive boilerplate, capturing several
common practices as mere keywords both easy and intuitive to use.

@item
Make startup time of Emacs as short as possible, without sacrificing
the quantity of add-on packages used.

@item
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.

@item
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.
@end enumerate

It is worth noting that use-package is not intended to replace the
standard customization command @w{@kbd{M-x customize}} (@pxref{Easy
Customization,,, emacs, GNU Emacs Manual}).  On the contrary, it is
designed to work together with it, for things that Customize cannot
do.

@c ----------------------------------------------------------------------------
@node Getting Started
@chapter Getting Started
@cindex quick-start instructions

This chapter provides instructions and examples for quickly getting
started with use-package.  In this manual, we say that each call to
the @code{use-package} macro in your init file is a @dfn{declaration},
to highlight the declarative nature of its syntax.

To unconditionally load a package named @samp{foo}, add the following
declaration to your init file:

@lisp
(use-package foo)
@end lisp

@noindent
This declaration is equivalent to using @code{require} (@pxref{Named
Features,,, elisp, GNU Emacs Lisp Reference Manual}), with some
use-package specific error handling added in.  Just like
@code{require}, it needs the package @samp{foo} to be installed and
available via your @code{load-path} (@pxref{Installing packages}).

To evaluate some Lisp @emph{before} the @samp{foo} package is loaded,
use the @code{:init} keyword:

@lisp
@group
(use-package foo
  :init
  (setq foo-variable t))
@end group
@end lisp

Similarly, @code{:config} can be used to execute code @emph{after} a
package is loaded.  In cases where loading is done lazily
(@pxref{Loading Packages}), this execution is deferred until after the
loading actually occurs.  As you might expect, you can use
@code{:init} and @code{:config} together:

@lisp
@group
(use-package foo
  :init
  (setq foo-variable t)
  :config
  (foo-mode 1))
@end group
@end lisp

The above declarations will load the @samp{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 (this is known as
``autoloading'').  If you have installed a package from @acronym{GNU}
@acronym{ELPA} that provides its own autoloads, it is often enough to
say:

@lisp
@group
(use-package foo
  :defer t)
@end group
@end lisp

@noindent
This will avoid loading the package.  Now, when you run any autoloaded
command, the package @samp{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
@code{isearch-moccur} and @code{isearch-all} from the package
@file{color-moccur.el}, and binds keys both globally and in
@code{isearch-mode-map}.  When one of these two commands are used, the
package will be loaded.  At that point, @code{moccur-edit} is also loaded,
to allow editing of the @code{moccur} buffer.

@lisp
@group
(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))
@end group
@end lisp

Some packages will suggest ready-made @code{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!

@c ----------------------------------------------------------------------------
@node Loading Packages
@chapter Loading Packages
@cindex loading packages with use-package

Before use-package can load an Emacs Lisp package, it must be
available in a directory on your @code{load-path}.  When you install
packages using the built-in @code{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 @code{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 @samp{package.el} to install packages
on Emacs start.  @xref{Installing packages}, for details.

@menu
* Loading basics::              How and when packages are loaded.
* Deferring loading::           Loading packages later.
* Forcing loading::             Loading packages immediately.
* Conditional loading::         Loading packages conditionally.
* Loading sequentially::        Loading packages in sequence.
* The @code{emacs} package::    Customizing built-in variables.
* Load dependencies::           Don't load without dependencies.
* Manual installation::         Loading manually installed packages.
@end menu

@node Loading basics
@section How and when use-package loads packages

The call to the @code{use-package} macro will load a package either
immediately, or when the package is first used (via autoloading).  In the
simplest case, a @code{use-package} declaration loads a package when
it is evaluated.@footnote{This happens both at run-time and at
compile-time.  @xref{Byte-compiling}.}  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
@code{foo}, just like @code{require} would:

@lisp
(use-package foo)
@end lisp

@noindent
If the library @samp{foo} is not available in your @code{load-path},
the declaration logs a warning to the @samp{*Messages*} buffer.

@cindex package vs library
@c So, confusingly, (use-package foo) actually means to use the
@c _library_ foo.el, not all of the _package_ foo's libraries?
@c Should this be explicitly explained here?
Note that a ``package'' is different from an Emacs Lisp ``library''.
The above declaration tells use-package to load the @emph{library}
@file{foo.el}, which in the overwhelming majority of cases also
resides in a @emph{package} named @code{foo}.  But the package
@code{foo} might also contain a library named @file{foo-extra.el}.  If
that library is not loaded automatically, you will need a separate
@code{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.

@node Deferring loading
@section Deferring package loading
@cindex deferring loading of package

@cindex autoloading packages
@cindex loading lazily
@cindex lazy loading of packages
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 @kbd{M-x} or via some key
binding).  This is based on autoloading, a full description of which
is outside the scope of this manual.  @xref{Autoload,,, elisp, GNU
Emacs Lisp Reference Manual}, for the full story.

@cindex triggers, for loading packages
Some @code{use-package} keywords provide autoload @dfn{triggers} that
cause a package to be loaded when certain events occur.  For example,
the @code{: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 @code{:commands}, @code{:bind}, @code{:bind*},
@code{:bind-keymap}, @code{:bind-keymap*}, @code{:mode}, and
@code{:interpreter}.

@subheading The @code{:defer} keyword

@findex :defer
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 @code{:defer} keyword.
It takes one boolean argument: a non-@code{nil} value means to stop
this package from being immediately loaded.  Here is an example of
using @code{:defer} to postpone loading the package @samp{foo}:

@lisp
@group
(use-package foo
  :defer t)
@end group
@end lisp

Using @code{:defer t} by itself like this is rarely useful.
Typically, you would only use it together with a keyword like
@code{:config} (@pxref{Lisp Configuration}), or @code{:ensure}
(@pxref{Installing packages}).

@subheading Defer loading until idle for N seconds

@findex :defer@r{, with a numeric argument}
You can also give a numeric argument @var{n} to @w{@code{:defer}} to
specify that a package should be loaded (if it hasn't already) after
Emacs has been idle for @var{n} seconds.  For example, use the
following to make use-package load @samp{foo} after 30 seconds of idle
time:

@lisp
@group
(use-package foo
  :defer 30)
@end group
@end lisp

@subheading When to use @code{:defer}

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

You should use @code{: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 @code{package-install}, as
packages installed in this way normally always have their own
autoloads already set up.

@subheading Making @w{@code{:defer t}} the default

@cindex defer loading by default
@cindex lazy loading by default
@vindex use-package-always-defer
If you customize the user option @code{use-package-always-defer} to
non-@code{nil}, the @code{use-package} macro will behave as if
@w{@code{:defer t}} is always specified.  This can be overridden for
individual declarations using either @w{@code{:defer nil}} or
@w{@code{:demand t}} (@pxref{Forcing loading}).

@node Forcing loading
@section Forcing package to load immediately
@cindex forcing immediate loading

@findex :demand
The presence of autoloading trigger keywords can be overridden using
@code{:demand t}, which forces the package to load immediately.  Thus,
even if you use an autoloading keyword such as @code{:bind}
(@pxref{Key bindings}), adding @code{: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 @w{@code{:demand t}} and @w{@code{:defer t}}, the
@code{:defer} keyword will take precedence.

@node Conditional loading
@section Loading packages conditionally
@cindex conditional loading
@cindex loading conditions

@findex :if
@findex :when
@findex :unless
The @code{:if}, @code{:when}, and @code{: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 @code{:if} keyword evaluates to non-@code{nil},
the package will be loaded and initialized.  The @code{:when} keyword
is provided as an alias for @code{:if}.  Finally, the @code{:unless}
keyword is the inverse of @code{:if}, such that @w{@code{:unless foo}}
means the same thing as @w{@code{:if (not foo)}}.

For example, if you only want to load @samp{foo} in graphical Emacs
sessions, you could use the following:

@lisp
@group
(use-package foo
  :if (display-graphic-p))
@end group
@end lisp

@subheading Some common use cases

Here are some common cases for conditional loading, and how to achieve
them.

@c FIXME: Too many redundant examples?  E.g., why do we need both an
@c example for system-type and window-system? or both of the last 2
@c examples?
@itemize

@item
Operating system

The following example loads a package only on GNU/Linux.  See the
docstring of @code{system-type} for other valid values.

@lisp
:if (eq system-type 'gnu/linux)
@end lisp

@item
Window system

The example below loads a package only on macOS and X@.  See the
docstring of @code{window-system} for valid values.

@lisp
:if (memq window-system '(ns x))
@end lisp

@item
Installed package

The following example loads a package only when the @samp{foo} package
is installed.

@lisp
:if (package-installed-p 'foo)
@end lisp

@item
Libraries in @code{load-path}

The example below loads a package only when @file{foo.el} is available
in your @code{load-path} (for example, if you installed that file
manually):

@lisp
:if (locate-library "foo.el")
@end lisp
@end itemize

@subheading Making conditional loading affect @code{:preface} and @code{:ensure}

@cindex conditional loading before @code{:preface} or @code{:ensure}
If you need to make a use-package form conditional so that the condition
occurs before even @code{:ensure} (@pxref{Install package}) or
@code{:preface} (@pxref{Preface keyword}), use @code{when}
around the @code{use-package} form itself.  For example:

@lisp
@group
(when (memq window-system '(mac ns))
  (use-package foo
    :ensure t))
@end group
@end lisp

@node Loading sequentially
@section Loading packages in sequence
@cindex loading a package after other packages

@findex :after
Sometimes it only makes sense to configure a package after another one
has been loaded, because certain variables or functions are not in
scope until that time.  This can be achieved with the @code{:after}
keyword, which allows a fairly rich description of the exact
conditions when loading should occur.  The @code{:after} keyword takes
as argument either a symbol indicating the package name, a list of
such symbols, or a list of selectors (see below).

Here is an example of using the @acronym{GNU} @acronym{ELPA} packages
@file{hydra}, @file{ivy}, and @file{ivy-hydra}.  Note that
@file{ivy-hydra} will always be loaded last:

@lisp
(use-package hydra)

(use-package ivy)

@group
(use-package ivy-hydra
  :after (ivy hydra))
@end group
@end lisp

In this case, because the declarations are evaluated in the order they
occur, the use of @code{:after} is not strictly necessary.  However,
if @samp{hydra} and @samp{ivy} were to be autoloaded, using
@code{:after} guarantees that @samp{ivy-hydra} is not loaded until it
is actually needed.  By using @code{:after}, the above code will also
work even if the order of the declaration changes.  This means that
moving things around in your init file is less likely to break things.

@subheading Using @code{:after} selectors

@findex :all@r{, (with @code{:after})}
@findex :any@r{, (with @code{:after})}
@cindex list of selectors, for @code{:after}
The @code{:after} keyword also accepts a list of selectors.  By
default, @w{@code{:after (foo bar)}} is the same as @w{@code{:after
(:all foo bar)}}, meaning that loading of the given package will not happen
until both @code{foo} and @code{bar} have been loaded.  Here are some
of the other possibilities:

@verbatim
:after (foo bar)
:after (:all foo bar)
:after (:any foo bar)
:after (:all (:any foo bar) (:any baz quux))
:after (:any (:all foo bar) (:all baz quux))
@end verbatim

When you nest selectors, such as in @w{@code{(:any (:all foo bar)
(:all baz quux))}}, it means that the package will be loaded when
either both @code{foo} and @code{bar} have been loaded, or when both
@code{baz} and @code{quux} have been loaded.

@cindex @code{use-package-always-defer}, with @code{:after}
Pay attention when setting @code{use-package-always-defer} to a
non-@code{nil} value, and also using the @code{:after} keyword.  In
that case, you will need to specify how the declared package is to be
loaded: for example, by some @code{:bind} (@pxref{Global
keybindings}).  If you are not using one of the keywords that
registers autoloads, such as @code{:bind} or @code{:hook}
(@pxref{Hooks}), and your package manager does not provide autoloads,
it is possible that your package will never be loaded if you do not
add @code{:demand t} to those declarations.

@node The @code{emacs} package
@section Customizing built-in variables
@cindex customizing built-in variables

Some users want to put all their customizations in use-package
declarations, even for variables, hooks, and options that are always
available, without loading any package.@footnote{In other words, they
are either preloaded in Emacs or defined in Emacs's C sources.}

For that purpose, you can use the no-op @samp{emacs} package:

@lisp
@group
(use-package emacs
  :init
  (setq custom-file "~/.emacs.d/emacs-custom.el")
  (load custom-file)
  (setq frame-title-format "%b")
  :custom
  (use-short-answers t))
@end group
@end lisp

This declaration takes advantage of the fact that @w{@code{(featurep
'emacs)}} always returns true, and has no special meaning beyond that.
It simply provides a way to organize your customizations, without
loading anything.

@node Load dependencies
@section Prevent loading if dependencies are missing
@cindex prevent loading package if dependencies are missing

@findex :requires
While the @code{:after} keyword delays loading until the dependencies
are loaded, the somewhat simpler @code{:requires} keyword @emph{never}
loads the package if the dependencies are not available when the
@code{use-package} declaration is evaluated.  In this context,
``available'' means that @code{foo} is available if @w{@code{(featurep
'foo)}} evaluates to a non-@code{nil} value.  For example:

@lisp
@group
(use-package abbrev
  :requires foo)
@end group
@end lisp

@noindent
This is the same as:

@lisp
@group
(use-package abbrev
  :if (featurep 'foo))
@end group
@end lisp

As a convenience, a list of such packages may be specified:

@lisp
@group
(use-package abbrev
  :requires (foo bar baz))
@end group
@end lisp

For more complex logic, such as that supported by @code{:after},
simply use @code{:if} and the appropriate Lisp expression.

@node Manual installation
@section Manually installed package

When installing packages manually, without Emacs's built-in package
manager (@file{package.el}), it will obviously not help you set up
autoloads or add it to your @code{load-path}.  You must do it
yourself.  However, use-package makes this more convenient.

@menu
* Load path::                   Using a custom @code{load-path}.
* Manual autoloads::            Setting up autoloads manually.
@end menu

@node Load path
@subsection Setting a custom @code{load-path}
@cindex custom @code{load-path} for loading a package
@cindex @code{load-path}, add directories for loading a package

When installing packages manually, you must make sure its libraries
are available on your @code{load-path}.  @xref{Lisp Libraries,,,
emacs, GNU Emacs Manual}, for more details about package loading.

@findex :load-path
The @code{:load-path} keyword provides a convenient way to add
directories to your load path.  It takes as argument a symbol, a
function, a string or a list of strings.  If a directory is specified
as a relative file name, it is expanded relative to
@code{user-emacs-directory}.

For example:

@lisp
@group
(use-package org
  :load-path "site-lisp/org/lisp/"
  :commands org-mode)
@end group
@end lisp

When using a symbol or a function to provide a dynamically generated
list of directories, you must inform the byte-compiler of this
definition, so that the value is available at byte-compilation time.
This is done by using the special form @code{eval-and-compile} (as
opposed to @code{eval-when-compile}, @pxref{Eval During Compile,,,
elisp, GNU Emacs Lisp Reference Manual}).  Furthermore, this value is
fixed to the value it had during compilation.  If the operation is
costly, you do not have to repeat it again on each startup.  For
example:

@lisp
@group
(eval-and-compile
  (defun ess-site-load-path ()
    (shell-command-to-string "find ~ -path ess/lisp")))
@end group

@group
(use-package ess-site
  :load-path (lambda () (list (ess-site-load-path)))
  :commands R)
@end group
@end lisp

@node Manual autoloads
@subsection Setting up autoloads manually

Packages often document how to set up its autoloads when it is being
manually installed.  If it does, follow those instructions.
Otherwise, you might want to set them up manually.

@cindex autoloads for packages, setting up manually
@cindex package autoloads, setting up manually

@findex :commands
@findex :autoload
To autoload an interactive command, use the @code{:commands} keyword,
which takes either a symbol or a list of symbols as its argument.  It
creates autoloads for those commands (which defers loading of the
module until those commands are used).

The @code{:autoload} keyword takes the same arguments as
@code{:commands}, but is used to autoload non-interactive functions.
Here is an example:

@lisp
@group
(use-package org-crypt
  :autoload org-crypt-use-before-save-magic)
@end group
@end lisp

@c ----------------------------------------------------------------------------
@node Configuring Packages
@chapter Configuring Packages
@cindex configure packages using @code{use-package}
@cindex customize package configuration

This chapter describes the various keywords provided by
@code{use-package} that help you configure packages.

@menu
* Lisp Configuration::          Using Lisp to configure packages.
* Key bindings::                Making your own keybindings.
* Hooks::                       Adding functions to hooks.
* Modes and interpreters::      Enabling modes automatically.
* Magic handlers::              Using regexps to enable modes.
* User options::                Setting user options.
* Faces::                       Customizing faces.
* Hiding minor modes::          Tidying up the mode line.
@end menu

@node Lisp Configuration
@section Using Lisp code for configuring packages
@cindex configure package using Lisp forms

The most general way to add customizations are the @code{:preface},
@code{:init}, and @code{:config} keywords.  They all accept one or
more Emacs Lisp forms, up to the next keyword, that are evaluated in
order.  This lets you add arbitrary Lisp code to your
@code{use-package} declarations.

The only difference between these keywords is when they are evaluated.

@menu
* Preface keyword::             Evaluate code before anything else.
* Init keyword::                Evaluate code before loading package.
* Config keyword::              Evaluate code after loading package.
* Best practices::              When to use @code{:config}, @code{:init}, and @code{:preface}.
@end menu

@node Preface keyword
@subsection @code{:preface} is evaluated first

@findex :preface
The @code{:preface} section is evaluated before anything else, except
@code{:disabled} and @code{:ensure}.  It can be used to establish
function and variable definitions that will:

@enumerate
@item
Make the byte-compiler happy: it will not complain about functions
whose definitions are unknown.

@item
Define functions and variables that will be used in an @code{:if}
test.
@end enumerate

Note that whatever is specified within @code{:preface} is evaluated
both at load time and at byte-compilation time, in order to ensure
that definitions are seen by both the Lisp evaluator and the
byte-compiler.  Therefore, you should avoid having any side-effects in
your @code{:preface} forms, and restrict them to symbol declarations
and definitions.

@node Init keyword
@subsection @code{:init} is evaluated before loading package

@findex :init
The @code{:init} section is evaluated just before the package is
loaded.  Note that the @code{:init} form is run unconditionally --
even if the package happens to not exist on your system.  You must
therefore remember to restrict @code{:init} code to what would succeed
either way; put the rest in the @code{:config} section.  @code{:init}
also always happens before package load, whether @code{:config} has
been deferred or not.

@node Config keyword
@subsection @code{:config} is evaluated after loading package

@findex :config
The @code{:config} section is evaluated after the package has been
loaded.  If the package is loaded immediately, this happens
immediately after that, but if loading is done lazily (@pxref{Loading
Packages}), this is deferred until after the package has been loaded.

In general, you should keep @code{:init} forms as simple and quick as
possible, and put as much as you can get away with into the
@code{:config} section.  That way, deferred loading can help your
Emacs start as quickly as possible.

@node Best practices
@subsection When to use @code{:preface}, @code{:config} and @code{:init}?
@cindex tips for using @code{:preface}, @code{:config}, @code{:init}

Where possible, it is better to avoid @code{:preface}, @code{:config}
and @code{:init}.  Instead, prefer autoloading keywords such as
@code{:bind} (@pxref{Key bindings}), @code{:hook} (@pxref{Hooks}), and
@code{:mode} (@pxref{Modes and interpreters}), as they will take care
of setting up autoloads for you without any need for boilerplate code.
For example, consider the following declaration:

@lisp
@group
(use-package foo
  :init
  (add-hook 'some-hook 'foo-mode))
@end group
@end lisp

@noindent
This has two problems.  First, it will unconditionally load the
package @samp{foo} on startup, which will make things slower.  You can
fix this by adding @w{@code{:defer t}}:

@lisp
@group
(use-package foo
  :defer t
  :init
  (add-hook 'some-hook 'foo-mode))
@end group
@end lisp

@noindent
This is better, as @samp{foo} is now only loaded when it is actually
needed (that is, when the hook @samp{some-hook} is run).

The second problem is that there is a lot of boilerplate that you have
to write.  In this case, it might not be so bad, but avoiding that was
what use-package was made to allow.  The better option in this case is
therefore to use @code{:hook} (@pxref{Hooks}), which also implies
@w{@code{:defer t}}.  The above is thereby reduced down to:

@lisp
@group
(use-package foo
  :hook some-hook)
@end group
@end lisp

Now use-package will set up autoloading for you, and your Emacs
startup time will not suffer one bit.

@node Key bindings
@section Key bindings

@cindex binding keys for package commands
@cindex key bindings for package commands
One common thing to do when loading a package is to bind keys to
commands within that module.  Without use-package, this would be done
using a combination of @code{keymap-local-set},
@code{keymap-global-set} and various autoloads.  With use-package, you
can simplify this using the @code{:bind} keyword, as described in this
section.

@menu
* Global keybindings::          Bindings you can use anywhere.
* Binding in keymaps::          Bindings for particular modes.
* Binding to a keymap::         Binding a key to a keymap.
* Binding to repeat-maps::      Binding repeating keys.
* Displaying keybindings::      Displaying personal key bindings.
@end menu

@node Global keybindings
@subsection Global keybindings
@cindex global keybindings

@findex :bind
To bind keys globally, the @code{:bind} keyword takes as its argument
either a single cons or a list of conses.  Each cons has the form
@w{@code{(@var{key} . @var{command})}}, where @var{key} is a string
indicating the key to bind, and @var{command} is the name of a command
(a symbol).  The syntax for the keys is similar to the syntax used by
the @code{kbd} function (see @ref{Init Rebinding,,, emacs, GNU Emacs
Manual}, for more information).

@subheading Using @code{:bind} with a single cons

Here is an example of using a single cons:

@lisp
@group
(use-package ace-jump-mode
  :bind ("C-." . ace-jump-mode))
@end group
@end lisp

@noindent
This does two things: first, it creates an autoload for the
@code{ace-jump-mode} command and defers loading of the
@code{ace-jump-mode} package until you actually use it.  Second, it
binds the key @code{C-.} to that command globally.

@subheading Using @code{:bind} with a list of conses

Here is an example of using @code{:bind} with a list of conses:

@lisp
@group
(use-package hi-lock
  :bind (("M-o l" . highlight-lines-matching-regexp)
         ("M-o r" . highlight-regexp)
         ("M-o w" . highlight-phrase)))
@end group
@end lisp

@noindent
This binds the three key sequences to the corresponding commands.

@subheading Using special keys
@cindex binding function keys with @code{:bind}
@cindex @code{:bind}, and function keys

@c FIXME: TAB vs [tab] -- is letter-case important?  In general, these
@c are two different keys: one is an ASCII character, the other a
@c function key on GUI frames.
Inside key strings, special keys like @kbd{TAB} or @kbd{F1}--@kbd{F12}
have to be written inside angle brackets, e.g., @code{"C-<up>"}.
@c FIXME: ``Some combinations''? which ones?
Standalone special keys (and some combinations) can be written in
square brackets, e.g.@ @code{[tab]} instead of @code{"<tab>"}.

Examples:

@lisp
@group
(use-package helm
  :bind (("M-x" . helm-M-x)
         ("M-<f5>" . helm-find-files)
         ([f10] . helm-buffers-list)
         ([S-f10] . helm-recentf)))
@end group
@end lisp

@subheading Remapping commands
@cindex remapping commands with @code{:bind}
@cindex @code{:bind}, and remapping of commands

Remapping of commands with @code{:bind} and @code{bind-key} works as
expected, because when the binding is a vector, it is passed straight
to @code{define-key}.  @xref{Remapping Commands,,, elisp, GNU Emacs
Lisp Reference Manual}, for more information about command remapping.
For example, the following declaration will rebind
@code{fill-paragraph} (bound to @kbd{M-q} by default) to
@code{unfill-toggle}:

@lisp
@group
(use-package unfill
  :bind ([remap fill-paragraph] . unfill-toggle))
@end group
@end lisp

@c FIXME: Should the below be an Appendix?
@subheading What @code{:bind} does behind the scenes
@cindex @code{:bind}, internals

To understand what @code{:bind} does behind the scenes, it might be
useful to consider an example:

@lisp
@group
(use-package ace-jump-mode
  :bind ("C-." . ace-jump-mode))
@end group
@end lisp

@noindent
This could be expressed in a much more verbose way with the
@code{:commands} and @code{:init} keywords:

@lisp
@group
(use-package ace-jump-mode
  :commands ace-jump-mode
  :init
  (bind-key "C-." 'ace-jump-mode))
@end group
@end lisp

@noindent
Without using even the @code{:commands} keyword, we could also write
the above like so:

@lisp
@group
(use-package ace-jump-mode
  :defer t
  :init
  (autoload 'ace-jump-mode "ace-jump-mode" nil t)
  (bind-key "C-." 'ace-jump-mode))
@end group
@end lisp

Although these three forms are all equivalent, the first form is
usually the best, as it will save some typing.

@node Binding in keymaps
@subsection Key bindings in local keymaps
@cindex local keybindings

@findex :map@r{, inside} :bind
Slightly different from binding a key to a keymap, is binding a key
@emph{within} a local keymap that only exists after the package is
loaded.  @code{use-package} supports this with a @code{:map} modifier,
taking the local keymap to bind to:

@lisp
@group
(use-package helm
  :bind (:map helm-command-map
         ("C-c h" . helm-execute-persistent-action)))
@end group
@end lisp

@noindent
The effect of this is to wait until @code{helm} has loaded, and then
to bind the key sequence @kbd{C-c h} to
@code{helm-execute-persistent-action} within Helm's local keymap,
@code{helm-command-map}.

Multiple uses of @code{:map} may be specified.  Any binding occurring
before the first use of @code{:map} are applied to the global keymap:

@lisp
@group
(use-package term
  :bind (("C-c t" . term)
         :map term-mode-map
         ("M-p" . term-send-up)
         ("M-n" . term-send-down)
         :map term-raw-map
         ("M-o" . other-window)
         ("M-p" . term-send-up)
         ("M-n" . term-send-down)))
@end group
@end lisp

@node Binding to a keymap
@subsection Binding to keymaps
@cindex binding keys to keymaps

@findex :bind-keymap
Normally @code{:bind} expects that commands are functions that will be
autoloaded from the given package.  However, this does not work if one of
those commands is actually a keymap, since keymaps are not functions,
and cannot be autoloaded using the built-in @code{autoload} function.

To handle this case, @code{use-package} offers a special, limited
variant of @code{:bind} called @code{:bind-keymap}.  The only difference
is that the ``commands'' bound to by @code{:bind-keymap} must be keymaps
defined in the package, rather than interactive functions.  This is handled
behind the scenes by generating custom code that loads the package
containing the keymap, and then re-executes your keypress after the
first load, to reinterpret that keypress as a prefix key.

For example:

@lisp
@group
(use-package foo
  :bind-keymap ("C-c p" . foo-command-map))
@end group
@end lisp

@node Binding to repeat-maps
@subsection Binding to repeat-maps
@cindex keybinding for @code{repeat-mode} keymaps

@findex :repeat-map@r{, inside} :bind
@cindex @code{repeat-mode} and use-package, using
A special case of binding within a local keymap is when that keymap is
used by @code{repeat-mode} (@pxref{Repeating,,, emacs, GNU Emacs
Manual}).  These keymaps are usually defined specifically for
this.  Using the @code{:repeat-map} keyword, and passing it a name for
the map it defines, will bind all the following keys inside that map, and
(by default) set the @code{repeat-map} property of each bound command
to that map.

The following example creates a keymap called
@code{git-gutter+-repeat-map}, makes four bindings in it, then sets
the @code{repeat-map} property of each bound command
(@code{git-gutter+-next-hunk}, @code{git-gutter+-previous-hunk},
@code{git-gutter+-stage-hunks}, and @code{git-gutter+-revert-hunk}) to
that keymap.

@lisp
@group
(use-package git-gutter+
  :bind
  (:repeat-map git-gutter+-repeat-map
   ("n" . git-gutter+-next-hunk)
   ("p" . git-gutter+-previous-hunk)
   ("s" . git-gutter+-stage-hunks)
   ("r" . git-gutter+-revert-hunk)))
@end group
@end lisp

@findex :exit@r{, inside} :repeat-map@r{ and} :bind
@cindex binding commands used at end of repeat series
Specifying @code{:exit} inside the scope of @code{:repeat-map} will
prevent the @code{repeat-map} property from being set, so that the command
can be used from within the repeat map, but after using it the repeat
map will no longer be available.  This is useful for commands often used
at the end of a series of repeated commands.  Example:

@lisp
@group
(use-package git-gutter+
  :bind
  (:repeat-map my/git-gutter+-repeat-map
   ("n" . git-gutter+-next-hunk)
   ("p" . git-gutter+-previous-hunk)
   ("s" . git-gutter+-stage-hunks)
   ("r" . git-gutter+-revert-hunk)
   :exit
   ("c" . magit-commit-create)
   ("C" . magit-commit)
   ("b" . magit-blame)))
@end group
@end lisp

@findex :continue@r{, inside} :repeat-map@r{ and} :bind
Specifying @code{:continue} @emph{forces} setting the
@code{repeat-map} property (just like @emph{not} specifying
@code{:exit}), so the above snippet is equivalent to:

@lisp
@group
(use-package git-gutter+
  :bind
  (:repeat-map my/git-gutter+-repeat-map
   :exit
   ("c" . magit-commit-create)
   ("C" . magit-commit)
   ("b" . magit-blame)
   :continue
   ("n" . git-gutter+-next-hunk)
   ("p" . git-gutter+-previous-hunk)
   ("s" . git-gutter+-stage-hunks)
   ("r" . git-gutter+-revert-hunk)))
@end group
@end lisp

@node Displaying keybindings
@subsection Displaying personal keybindings
@cindex display your keybindings

@findex describe-personal-keybindings
The @code{:bind} keyword uses the @code{bind-keys} macro from the
@samp{bind-key.el} library to set up keybindings.  It keeps track of
all keybindings you make, so that you can display them separately from
the default keybindings.

Use @w{@kbd{M-x describe-personal-keybindings}} to see all
keybindings you've set using either the @code{:bind} keyword or the
@code{bind-keys} macro.

@node Hooks
@section Hooks

@cindex hooks
@findex :hook
The @code{:hook} keyword allows adding functions to hooks.  It takes
@c FIXME: The actual forms accepted by :hook are different, see below!
one argument of the form @var{hooks}, specifying one or more functions
to add to one or more hooks.  For the purposes of @code{:hook}, the
name of hook variables should always exclude the @samp{-hook} suffix.
It is appended automatically for you, to save some typing.

For example, consider the following @code{use-package} declaration
that sets up autoloads for @code{company-mode} from the @samp{company}
package, and adds @samp{company-mode} to @code{prog-mode-hook}:

@lisp
@group
(use-package company
  :commands company-mode
  :init
  (add-hook 'prog-mode-hook #'company-mode))
@end group
@end lisp

Using @code{:hook}, this can be simplified to:

@lisp
@group
(use-package company
  :hook (prog-mode . company-mode))
@end group
@end lisp

Here, @code{:hook} will automatically set up autoloads for the
@code{company-mode} command, so there is no need to use
@code{:commands}.

The @code{:hook} keyword will also assume that the name of the
function you want to add is the same as the package name with
@samp{-mode} appended to it.  Taking this into account, you can
simplify the above to the equivalent:

@lisp
@group
(use-package company
  :hook prog-mode)
@end group
@end lisp

@cindex multiple hooks
You can also provide a list of hooks.  When multiple hooks should be
applied, the following examples are all equivalent:

@lisp
@group
(use-package company
  :hook (prog-mode text-mode))
@end group

@group
(use-package company
  :hook ((prog-mode text-mode) . company-mode))
@end group

@group
(use-package company
  :hook ((prog-mode . company-mode)
         (text-mode . company-mode)))
@end group

@group
(use-package company
  :commands company-mode
  :init
  (add-hook 'prog-mode-hook #'company-mode)
  (add-hook 'text-mode-hook #'company-mode))
@end group
@end lisp

One common mistake when using @code{:hook} is to forget to omit the
@samp{-hook} suffix, which, as already explained, is appended
automatically.  Therefore, the following will not work, as it attempts
to add a function to non-existent @code{prog-mode-hook-hook}:

@lisp
@group
;; DOES NOT WORK
(use-package ace-jump-mode
  :hook (prog-mode-hook . ace-jump-mode))
@end group
@end lisp

@vindex use-package-hook-name-suffix
If you do not like this behavior, you can customize the user option
@code{use-package-hook-name-suffix} to @code{nil}.  The value of this
variable is @samp{"-hook"} by default.

The use of @code{:hook}, as with @code{:bind}, @code{:mode},
@code{:interpreter}, etc., causes the functions being hooked to
implicitly be read as @code{:commands}.  This means that they will
establish interactive @code{autoload} definitions for that module, if
not already defined as functions), and so @code{:defer t} is also
implied by @code{:hook}.

@node Modes and interpreters
@section Modes and interpreters
@cindex @code{auto-mode-alist} customization
@cindex @code{interpreter-mode-alist} customization
@cindex setting up major modes

@findex :mode
@findex :interpreter
Similar to @code{:bind}, you can use @code{:mode} and
@code{:interpreter} to establish a deferred binding within the
@code{auto-mode-alist} and @code{interpreter-mode-alist} variables
(@pxref{Auto Major Mode,,, elisp, GNU Emacs Lisp Reference Manual}).
The specifier to either keyword can be a cons cell, a list of cons
cells, or a string or regexp.

The following example reproduces the default @code{ruby-mode}
configuration, exactly as it is in Emacs out-of-the-box.  That mode is
enabled automatically when a file whose name matches the regexp
@code{"\\.rb\\'"} (a file with the @file{.rb} extension), or when the
first line of the file (known as the ``shebang'') matches the string
@code{"ruby"}:

@lisp
@group
(use-package ruby-mode
  :mode "\\.rb\\'"
  :interpreter "ruby")
@end group
@end lisp

The default @code{python-mode} configuration can be reproduced using
the declaration below.  Note that the package that should be loaded
differs from the mode name in this case, so we must use a cons:

@lisp
@group
;; The package is "python" but the mode is "python-mode":
(use-package python
  :mode ("\\.py\\'" . python-mode)
  :interpreter ("python" . python-mode))
@end group
@end lisp

Both the @code{:mode} and @code{:interpreter} keywords also accept a
list of regexps:

@lisp
@group
(use-package foo
  ;; Equivalent to "\\(ba[rz]\\)\\'":
  :mode ("\\.bar\\'" "\\.baz\\'")
  ;; Equivalent to "\\(foo[ab]\\)":
  :interpreter ("fooa" "foob"))
@end group
@end lisp

@node Magic handlers
@section Magic handlers
@cindex @code{magic-mode-alist} customization

@findex :magic
@findex :magic-fallback
Similar to @code{:mode} and @code{:interpreter}, you can also use
@code{:magic} and @code{:magic-fallback} to cause certain function to
be run if the beginning of a file matches a given regular expression,
as if these regular expressions were added to @code{magic-mode-alist}
and @code{magic-fallback-mode-alist} (@pxref{Auto Major Mode,,, elisp,
GNU Emacs Lisp Reference Manual}).  The difference between
@code{:magic} and @code{:magic-fallback}, is that the latter has a
lower priority than @code{:mode}.

Here is an example:

@lisp
@group
(use-package pdf-tools
  :magic ("%PDF" . pdf-view-mode)
  :config
  (pdf-tools-install :no-query))
@end group
@end lisp

This registers an autoloaded command for @code{pdf-view-mode}, defers
loading of @code{pdf-tools}, and runs @code{pdf-view-mode} if the
beginning of a buffer matches the string @code{"%PDF"}.

@node User options
@section User options
@cindex customization of variables
@cindex variable customizations
@cindex user options, setting

@findex :custom
In Emacs, you normally set customizable variables (user options) using
the @code{M-x customize} interface (@pxref{Easy Customization,,,
emacs, GNU Emacs Manual}).  We recommend this method for most users.
However, it is also possible to set them in your @code{use-package}
declarations by using the @code{:custom} keyword.

@lisp
@group
(use-package comint
  :defer t
  :custom
  (comint-buffer-maximum-size 20000 "Increase comint buffer size.")
  (comint-prompt-read-only t "Make the prompt read only."))
@end group
@end lisp

This is better than using @code{setq} in a @code{:config} block, as
customizable variables might have some code associated with it that
Emacs will execute when you assign values to them.  (In Emacs 29 and
later, there is also the new @code{setopt} macro that does this for
you.)

Note that the values customized using @code{:custom} are @emph{not}
saved in the standard Emacs @code{custom-file} (@pxref{Saving
Customizations,,, emacs, GNU Emacs Manual}).  You should therefore set
each user option using either the @code{:custom} keyword @emph{or}
@w{@kbd{M-x customize-option}} command; the latter will save
customized values in the Emacs @code{custom-file}.  Do not use both
for the same variable, as this risks having conflicting values in your
use-package declaration and your @code{custom-file}, which can lead to
problems that are both tricky and tedious to debug.

Also note that if you use @code{:custom} in a file that you
byte-compile, you could have some unexpected results if you later load
or @code{require} @file{use-package} (e.g., due to lazy loading): the
value of the corresponding user options could be reset back to their
initial values.  We therefore recommend against byte-compiling files
that use @file{use-package} with @code{:custom} settings.

@node Faces
@section Faces
@cindex faces, setting
@cindex customization of faces

@findex :custom-face
The @code{:custom-face} keyword allows customization of package's
faces.  Example:

@lisp
@group
(use-package eruby-mode
  :custom-face
  (eruby-standard-face ((t (:slant italic)))))
@end group

@group
(use-package example
  :custom-face
  (example-1-face ((t (:foreground "LightPink"))))
  (example-2-face ((t (:foreground "LightGreen"))) face-defspec-spec))
@end group

@group
(use-package zenburn-theme
  :preface
  (setq my/zenburn-colors-alist
        '((fg . "#DCDCCC") (bg . "#1C1C1C") (cyan . "#93E0E3")))
  :custom-face
  (region ((t (:background ,(alist-get my/zenburn-colors-alist 'cyan)))))
  :config
  (load-theme 'zenburn t))
@end group
@end lisp

@node Hiding minor modes
@section Hiding minor modes with diminish and delight
@cindex hiding minor modes

@code{use-package} supports the @file{diminish} and @file{delight}
packages, both of which make it possible to remove or change minor mode
strings in your mode-line.  Which one to use is up to you, but you
should normally only use one or the other -- never both.@footnote{When
in doubt, you might as well use @file{diminish}.}  To use either of them, you
must first install the corresponding package from @acronym{GNU} @acronym{ELPA}.

@menu
* Diminish::                    Hiding minor modes with Diminish.
* Delight::                     Hiding minor modes with Delight.
@end menu

@node Diminish
@subsection Diminish

@findex :diminish
When diminish@footnote{The @file{diminish} package is installable from
@acronym{GNU} @acronym{ELPA}.} is installed, you can use the @code{:diminish}
keyword.  If @file{diminish} is not installed, the @code{:diminish} keyword
does nothing.

First, add the following declaration to the beginning of your init
file.

@lisp
(use-package diminish :ensure t)
@end lisp

@noindent
The optional @w{@code{:ensure t}} makes sure the package is installed
if it isn't already (@pxref{Installing packages}).

The @code{:diminish} keyword takes as its argument either a minor mode
symbol, a cons of the symbol and its replacement string, or just a
replacement string, in which case the minor mode symbol is guessed to
be the package name with @samp{-mode} appended at the end:

@lisp
@group
(use-package abbrev
  :diminish abbrev-mode
  :config
  (if (file-exists-p abbrev-file-name)
      (quietly-read-abbrev-file)))
@end group
@end lisp

@node Delight
@subsection Delight

@findex :delight
When @file{delight}@footnote{The @file{delight} package is installable from
@acronym{GNU} @acronym{ELPA}.} is installed, you can use the
@code{:delight} keyword.  If @file{delight} is not installed, the
@code{:delight} keyword does nothing.

First, add the following declaration to the beginning of your init
file.

@lisp
(use-package delight :ensure t)
@end lisp

@noindent
The optional @w{@code{:ensure t}} makes sure the package is installed
if it isn't already (@pxref{Installing packages}).

The @code{:delight} keyword takes as its argument a minor mode symbol,
a replacement string, or quoted mode line data (in which case the
minor mode symbol is assumed to be the package name with @samp{-mode}
appended at the end), both of these, or several lists of both.
@xref{Mode Line Data,,, elisp, GNU Emacs Lisp Reference Manual}.  If
no arguments are provided, the default mode name is hidden completely.

For example, the following hides everything for the @samp{foo-mode}
minor mode in the @samp{foo} package:

@lisp
@group
(use-package foo
  :delight)
@end group
@end lisp

If the mode name doesn't match the package name with @samp{-mode}
appended, provide a symbol instead.  For example, the following hides
@code{auto-revert-mode} from the mode line:

@lisp
@group
;; Don't show anything for auto-revert-mode, which doesn't match
;; its package name.
(use-package autorevert
  :delight auto-revert-mode)
@end group
@end lisp

You can also use arbitrary Lisp code as argument of @code{:delight}.
For example, to replace @samp{foo-mode} with the value of the current
buffer:

@lisp
@group
(use-package foo
  :delight '(:eval buffer-file-name))
@end group
@end lisp

Here is an example of hiding several built-in minor modes:

@lisp
@group
;; Completely hide visual-line-mode and change auto-fill-mode to " AF".
(use-package emacs
  :delight
  (auto-fill-function " AF")
  (visual-line-mode))
@end group
@end lisp

@c ----------------------------------------------------------------------------
@node Installing packages
@chapter Installing packages automatically

The standard Emacs package manager is documented in the Emacs manual
(@pxref{Package Installation,,, emacs, GNU Emacs Manual}).  The
@code{use-package} macro provides the @code{:ensure} and @code{:pin}
keywords that interface with that package manager to automatically
install packages.  The @code{:vc} keyword may be used to control how
package sources are downloaded; e.g., from remote hosts
(@pxref{Fetching Package Sources,,, emacs, GNU Emacs Manual}).  This
is particularly useful if you use your init file on more than one
system.

@menu
* Install package::
* Pinning packages::
* Other package managers::
@end menu

@node Install package
@section Installing package
@cindex installing packages from archives

@findex :ensure
The @code{:ensure} keyword makes use-package ask the Emacs package
manager to install a package if it is not already present on your
system.

For example:

@lisp
@group
(use-package magit
  :ensure t)
@end group
@end lisp

If you need to install a different package from the one named by
@code{use-package}, you can use a symbol:

@lisp
@group
(use-package tex
  :ensure auctex)
@end group
@end lisp

@vindex use-package-always-ensure
You can customize the user option @code{use-package-always-ensure} to
a non-@code{nil} value if you want this behavior to be global for all
packages:

@lisp
@group
(require 'use-package-ensure)
(setq use-package-always-ensure t)
@end group
@end lisp

@noindent
You can override the above setting for a single package by adding
@w{@code{:ensure nil}} to its declaration.

@findex :vc
The @code{:vc} keyword can be used to control how packages are
downloaded and/or installed.  More specifically, it allows one to fetch
and update packages directly from a version control system.  This is
especially convenient when wanting to install a package that is not on
any package archive.

The keyword accepts the same arguments as specified in
@pxref{Fetching Package Sources,,, emacs, GNU Emacs Manual}, except
that a name need not explicitly be given: it is inferred from the
declaration.  The accepted property list is augmented by a @code{:rev}
keyword, which has the same shape as the @code{REV} argument to
@code{package-vc-install}.  Notably -- even when not specified --
@code{:rev} defaults to checking out the last release of the package.
You can use @code{:rev :newest} to check out the latest commit.

For example,

@example
@group
(use-package bbdb
  :vc (:url "https://git.savannah.nongnu.org/git/bbdb.git"
       :rev :newest))
@end group
@end example

would try -- by invoking @code{package-vc-install} -- to install the
latest commit of the package @code{foo} from the specified remote.

@vindex use-package-vc-prefer-newest
Alternatively, the @code{use-package-vc-prefer-newest} user option
exists to always prefer the latest commit.

The @code{:vc} keyword can also be used for local packages, by
combining it with @code{:load-path} (@pxref{Load path}):

@example
@group
;; Use a local copy of BBDB instead of the one from GNU ELPA.
(use-package bbdb
  :vc t
  :load-path "/path/to/bbdb/dir/")
@end group
@end example

The above dispatches to @code{package-vc-install-from-checkout}.

@node Pinning packages
@section Pinning packages using @code{:pin}
@cindex installing package from specific archive
@cindex pinning a package to archive

@findex :pin
use-package can @dfn{pin} a package to a specific archive using the
@code{:pin} keyword.@footnote{The @code{:pin} keyword has no effect on
Emacs versions older than 24.4.}  This allows you to mix and match
packages from different archives.  The primary use-case for this is
preferring to install packages from @acronym{GNU} @acronym{ELPA} or
@acronym{NonGNU} @acronym{ELPA} (indicated by @code{gnu} and @code{nongnu},
respectively), while installing specific packages from third-party
archives.

For example:

@lisp
@group
(use-package company
  :ensure t
  :pin gnu)   ; GNU ELPA
@end group
@end lisp

@vindex use-package-always-pin
Unfortunately, the third-party archive @acronym{MELPA} uses a
versioning scheme based on dates, which means that packages from that
archive are always preferred.  If you are using that archive, we
strongly encourage you to customize @code{use-package-always-pin} to
@code{nongnu}.  This guarantees that you are using a version of that
package that has been specifically marked for release by its
developer, and not a development snapshot.

@cindex manual update of packages
@c FIXME: This needs clarifying.  AFAIK, :ensure does not update packages.
If you want to manually keep a package updated and ignore upstream
updates, you can pin it to @samp{manual}.  This will work as long as
you have not customized a repository to use that name in the
@code{package-archives} variable.

Example:

@lisp
@group
(use-package org
  :ensure t
  ;; ignore org-mode from upstream and use a manually installed version
  :pin manual)
@end group
@end lisp

@code{use-package} signals an error if you try to pin a package to an
archive that is not configured using @code{package-archives} (except
from the special @samp{manual} archive).

@node Other package managers
@section Non-standard package managers
@cindex non-standard package managers
@cindex package managers, other than @file{package.el}
@cindex installing using non-standard package managers

By default, use-package assumes that you are using the Emacs built-in
@file{package.el} package manager.  We expect that most users will
find that it is capable enough, even for advanced use cases.

@vindex use-package-ensure-function
However, some users might prefer to use a third-party package manager
for a specific circumstance or use case.  By setting the user option
@code{use-package-ensure-function} to the name of a function, you can
direct @code{:ensure} to use a different package manager for
installing packages.

For more details, please see the documentation of the package manager
you are using.  If you run into any bugs, it is often best to report
them directly to the developers of that package manager.

@c ----------------------------------------------------------------------------
@node Byte-compiling
@chapter Byte-compiling your init file
@cindex byte-compiling your init file

Some users might want to byte-compile their init file to make Emacs
startup faster.  This is not recommended in most cases, as the
speed-up is usually too small to be worth it, and it can lead to
confusion if the byte-compiled files are out-of-date.  If you still
want to do it, this chapter explains how to do that.

@code{use-package} always loads every library that it can while a file
is being byte-compiled.  This helps silence spurious warnings about
unknown variables and functions.

@findex :defines
@findex :functions
@cindex silence byte-compilation warnings
However, there are times when this is just not enough.  For those
times, use the @code{:defines} and @code{:functions} keywords to
introduce dummy variable and function declarations solely for the sake
of silencing byte-compiler warnings.  For example:

@lisp
@group
(use-package texinfo
  :defines texinfo-section-list
  :commands texinfo-mode
  :init
  (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode)))
@end group
@end lisp

If you need to silence a missing function warning, you can use
@code{:functions}:

@lisp
@group
(use-package ruby-mode
  :mode "\\.rb\\'"
  :interpreter "ruby"
  :functions inf-ruby-keys
  :config
  (defun my-ruby-mode-hook ()
    (require 'inf-ruby)
    (inf-ruby-keys))
  (add-hook 'ruby-mode-hook 'my-ruby-mode-hook))
@end group
@end lisp

@findex :no-require
@cindex prevent a package from loading at compile-time
@cindex package loading at byte-compilation time, prevent
Normally, @code{use-package} will load each package at compile time
before compiling the configuration, to ensure that any necessary
symbols are in scope to satisfy the byte-compiler.  At times this can
cause problems, since a package may have special loading requirements,
and all that you want to use @code{use-package} for is to add a
configuration to the @code{eval-after-load} hook.  In such cases, use
the @code{:no-require} keyword:

@lisp
@group
(use-package foo
  :no-require t
  :config
  (message "Evaluate this immediately after loading `foo'"))
@end group
@end lisp

@c ----------------------------------------------------------------------------
@node Troubleshooting
@chapter Troubleshooting

@cindex troubleshooting use-package
@cindex debugging use-package
If an error occurs while initializing or configuring a package, this
will not stop your Emacs from loading.  Instead, @code{use-package}
captures the error and reports it in a special @file{*Warnings*} popup
buffer, so that you can debug the situation in an otherwise functional
Emacs.

If you are having trouble when starting Emacs, you can pass Emacs the
@samp{--debug-init} command line flag.  @xref{Initial Options,,,
emacs, GNU Emacs Manual}.  To get even more information when using
that flag, add the following to your init file (these options are
documented below):

@lisp
@group
(when init-file-debug
  (setq use-package-verbose t
        use-package-expand-minimally nil
        use-package-compute-statistics t
        debug-on-error t))
@end group
@end lisp

@cindex reporting bugs
@cindex expanding macro, for troubleshooting
Since @code{use-package} is a macro, the first step when you need to
dig deeper is usually to see what Emacs Lisp code your declaration
expands to.  You can either use the command @w{@kbd{M-x
pp-macroexpand-last-sexp}}, or wrap the use-package declaration in
@code{macroexpand} and evaluate it.  It is a good idea to include
their output in any bugs you file for use-package.

@menu
* Troubleshooting Options::
* Gathering Statistics::
* Disabling a package::
@end menu

@node Troubleshooting Options
@section Options that help when troubleshooting
@cindex options for troubleshooting
@cindex troubleshooting, options that help

@vindex use-package-expand-minimally
By default, use-package will attempts to catch and report errors that
occur during expansion of use-package declarations in your init file.
Customize the user option @code{use-package-expand-minimally} to a
non-@code{nil} value to disable this checking.

@findex :catch
This behavior may be overridden locally using the @code{:catch}
keyword.  If @code{t} or @code{nil}, it enables or disables catching
errors at load time.  It can also be a function taking two arguments:
the keyword being processed at the time the error was encountered, and
the error object (as generated by @code{condition-case}).  For
example:

@lisp
@group
(use-package example
  ;; Note that errors are never trapped in the preface, since
  ;; doing so would hide definitions from the byte-compiler.
  :preface (message "I'm here at byte-compile and load time")
  :init (message "I'm always here at startup")
  :config
  (message "I'm always here after the package is loaded")
  (error "oops")
  ;; Don't try to (require 'example), this is just an example!
  :no-require t
  :catch (lambda (keyword err)
           (message (error-message-string err))))
@end group
@end lisp

Evaluating the above form will print these messages:

@verbatim
I'm here at byte-compile and load time
I'm always here at startup
Configuring package example...
I'm always here after the package is loaded
oops
@end verbatim

@node Gathering Statistics
@section Gathering Statistics
@cindex gathering use-package statistics
@cindex usage statistics for use-package

@vindex use-package-verbose
When a package is loaded, and if you have @code{use-package-verbose}
set to @code{t}, or if the package takes longer than 0.1 seconds to
load, you will see a message to indicate this loading activity in the
@code{*Messages*} buffer.  The same will happen for configuration, or
@code{:config} blocks, that take longer than 0.1 seconds to execute.

@vindex use-package-compute-statistics
If you'd like to see a summary how many packages you've loaded, what
stage of initialization they've reached, and how much aggregate time
they've spent (roughly), you can customize the user option
@code{use-package-compute-statistics} to a non-@code{nil} value.  Then
reload your packages, normally by restarting Emacs, to make sure that
use-package can gather statistics for all your packages.

@cindex use-package-report
Run the command @kbd{M-x use-package-report} to see the results.  The
buffer displayed is a tabulated list.  To sort rows based on a
particular column, move point to it and type @kbd{S}, or click the
column name at the top of the buffer on graphical displays.

@findex use-package-reset-statistics
To reset all statistics that use-package has gathered for the current
Emacs invocation, run the command @kbd{M-x use-package-reset-statistics}.

Note that if you are setting @code{use-package-compute-statistics}
directly in your init file, and not with @code{customize}, you must do
this after loading @code{use-package}, but before any
@code{use-package} forms.

@node Disabling a package
@section Disabling a package
@cindex disable package

@findex :disabled
The @code{:disabled} keyword inhibits loading a package, and all its
customizations.  It is equivalent to commenting out or deleting the
definition.

You could use this, for example, to temporarily disable a package that
you're having difficulties with, or to avoid loading a package that
you're not currently using.

This example disables the @samp{foo} package:

@lisp
@group
(use-package foo
  :disabled)
@end group
@end lisp

When byte-compiling your init file, use-package omits disabled
declarations from the output entirely, in order to make Emacs startup
faster.

@c ----------------------------------------------------------------------------
@node Keyword extensions
@appendix Keyword extensions
@cindex keyword extension
@cindex extending use-package keywords

use-package is based on an extensible framework that makes it easy for
package authors to add new keywords, or modify the behavior of
existing keywords.

Some keyword extensions are included with @code{use-package}, and can
be optionally enabled.

@menu
* use-package-ensure-system-package::
* Creating an extension::
@end menu

@node use-package-ensure-system-package
@appendixsec :use-package-ensure-system-package

@findex :ensure-system-package
The @code{:ensure-system-package} keyword allows you to ensure certain
executables are available on your system alongside your package
declarations.@footnote{On macOS, your @code{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
@uref{https://github.com/purcell/exec-path-from-shell,@samp{exec-path-from-shell}}
package.}

To use this extension, add this immediately after loading
@code{use-package}:

@lisp
(use-package use-package-ensure-system-package)
@end lisp

Now you can use the @code{:ensure-system-package} keyword.
Here's an example usage:

@lisp
@group
(use-package foo
  :ensure-system-package foo)
@end group
@end lisp

This will expect a global binary package to exist called @code{foo}.
If it does not, it will use your system package manager to attempt an
install of a binary by the same name asynchronously.  This requires
the @acronym{GNU} @acronym{ELPA} package
@uref{https://gitlab.com/jabranham/system-packages,@samp{system-packages}},
so for this to work you must install that first.

One way of making sure it is installed is with @code{use-package}
together with @code{:ensure}.

@lisp
@group
(use-package system-packages
  :ensure t)
@end group
@end lisp

For example, on a Debian GNU/Linux system, this would call
@samp{apt-get install foo}.

If the package is named differently than the binary, you can use a
cons in the form of @code{(binary . package-name)}.  For example:

@lisp
@group
(use-package foo
  :ensure-system-package
  (foocmd . foo))
@end group
@end lisp

On a Debian GNU/Linux system, this would call @code{apt install foo}
if Emacs could not locate the executable @code{foocmd}.@footnote{For
manual testing, you could use the @code{executable-find} function,
which is what @samp{system-packages} uses internally.}

@code{:ensure-system-package} can also take a cons where the
@code{cdr} is a string that will get called by
@code{(async-shell-command)} to install if it isn't found.  This does
not depend on any external package.

@lisp
@group
(use-package tern
  :ensure-system-package (tern . "npm i -g tern"))
@end group
@end lisp

To install several packages, you can pass in a list of conses:

@lisp
@group
(use-package ruby-mode
  :ensure-system-package
  ((rubocop     . "gem install rubocop")
   (ruby-lint   . "gem install ruby-lint")
   (ripper-tags . "gem install ripper-tags")
   (pry         . "gem install pry")))
@end group
@end lisp

Finally, in case the package dependency does not provide a global
executable, you can ensure that packages exist by checking the
presence of a file by providing a string like so:

@lisp
@group
(use-package dash-at-point
  :if (eq system-type 'darwin)
  :ensure-system-package
  ("/Applications/Dash.app" . "brew cask install dash"))
@end group
@end lisp

@code{:ensure-system-package} will use @code{system-packages-install}
to install system packages, except where a custom command has been
specified, in which case it will be executed verbatim by
@code{async-shell-command}.

The user options @code{system-packages-package-manager} and
@code{system-packages-use-sudo} are honored, but not for custom
commands.  Custom commands should include the call to sudo in the
command if needed.

@node Creating an extension
@appendixsec How to create an extension keyword
@cindex extension keywords

This section describes how to create a new keyword.

@enumerate
@item
Add the keyword.

The first step is to add your keyword at the right place in
@code{use-package-keywords}.  This list determines the order in which
things will happen in the expanded code.  You should never change this
order, but it gives you a framework within which to decide when your
keyword should fire.

@item
Create a normalizer.

The job of the normalizer is take a list of arguments (possibly
@code{nil}), and turn it into the single argument (which could still
be a list) that should appear in the final property list used by
@code{use-package}.

Define a normalizer for your keyword by defining a function named
after the keyword, for example:

@lisp
@group
(defun use-package-normalize/:pin (name-symbol keyword args)
  (use-package-only-one (symbol-name keyword) args
    (lambda (label arg)
      (cond
       ((stringp arg) arg)
       ((symbolp arg) (symbol-name arg))
       (t
        (use-package-error
         ":pin wants an archive name (a string)"))))))
@end group
@end lisp

@item
Create a handler.

Once you have a normalizer, you must create a handler for the keyword.

Handlers can affect the handling of keywords in two ways.  First, they
can modify the @code{state} plist before recursively processing the
remaining keywords, to influence keywords that pay attention to the
state (one example is the state keyword @code{:deferred}, not to be
confused with the @code{use-package} keyword @code{:defer}).  Then,
once the remaining keywords have been handled and their resulting
forms returned, the handlers may manipulate, extend, or just ignore
those forms.

The task of each handler is to return a @emph{list of forms}
representing code to be inserted.  It does not need to be a
@code{progn} list, as this is handled automatically in other places.
Thus it is common to see the idiom of using @code{use-package-concat}
to add new functionality before or after a code body, so that only the
minimum code necessary is emitted as the result of a
@code{use-package} expansion.

This is an example handler:

@lisp
@group
(defun use-package-handler/:pin (name-symbol keyword archive-name rest state)
  (let ((body (use-package-process-keywords name-symbol rest state)))
    ;; This happens at macro expansion time, not when the expanded code is
    ;; compiled or evaluated.
    (if (null archive-name)
        body
      (use-package-pin-package name-symbol archive-name)
      (use-package-concat
       body
       `((push '(,name-symbol . ,archive-name)
               package-pinned-packages))))))
@end group
@end lisp

@item
Test it.

After the keyword has been inserted into @code{use-package-keywords},
and a normalizer and a handler has been defined, you can now test the
keyword by seeing how usages of the keyword will expand.  For this,
use @w{@kbd{M-x pp-macroexpand-last-sexp}} with the cursor set
immediately after the @code{(use-package @dots{})} expression.
@end enumerate

@c ----------------------------------------------------------------------------
@node History
@appendix History and acknowledgments

use-package was written by John Wiegley.  Its development started in
2012, and it got merged into Emacs in 2022, in preparation of the
release of Emacs 29.1.

Dozens of people have contributed to use-package over the years with
bug reports, documentation and code.  They are too many to list here,
but we thank them all for their contributions.

This Texinfo manual was written by Stefan Kangas, as a significant
rewrite of the old use-package manual and @file{README}.

@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi

@node Index
@unnumbered Index
@printindex cp

@bye