     [file docstyle.texi not included]
     [file emacsver.texi not included]

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 EMACSVER.

Copyright © 2022--2025 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.''

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:

 1. 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.

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

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

 4. 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.

 5. 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 (GNU Emacs Manual)).  On the contrary, it is designed to work together with it, for things that Customize cannot do.

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 (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).

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 (this is known as ``autoloading'').  If you have installed a package from GNU ELPA that provides its 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!

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, for details.

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. (This happens both at run-time and at compile-time.  See 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 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.

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 (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 Lisp Configuration), or :ensure (see Installing packages).

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 loading).

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.

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.

  * Operating system

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

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

  * Window system

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

          :if (memq window-system '(ns x))

  * Installed package

     The following example loads a package only when the foo package is installed.

          :if (package-installed-p 'foo)

  * Libraries in load-path

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

          :if (locate-library "foo.el")

Making conditional loading affect :preface and :ensure
------------------------------------------------------

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

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

Loading packages in sequence
============================

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 :after keyword, which allows a fairly rich description of the exact conditions when loading should occur.  The :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 GNU ELPA packages hydra, ivy, and ivy-hydra.  Note that ivy-hydra will always be loaded last:

     (use-package hydra)

     (use-package ivy)

     (use-package ivy-hydra
       :after (ivy hydra))

In this case, because the declarations are evaluated in the order they occur, the use of :after is not strictly necessary.  However, if hydra and ivy were to be autoloaded, using :after guarantees that ivy-hydra is not loaded until it is actually needed.  By using :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.

Using :after selectors
----------------------

The :after keyword also accepts a list of selectors.  By default, :after (foo bar) is the same as :after (:all foo bar), meaning that loading of the given package will not happen until both foo and bar have been loaded.  Here are some of the other possibilities:

: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))

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

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

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. (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 emacs package:

     (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))

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

Prevent loading if dependencies are missing
===========================================

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

     (use-package abbrev
       :requires foo)

This is the same as:

     (use-package abbrev
       :if (featurep 'foo))

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

     (use-package abbrev
       :requires (foo bar baz))

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

Manually installed package
==========================

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

Setting a custom load-path
--------------------------

When installing packages manually, you must make sure its libraries are available on your load-path.  See Lisp Libraries (GNU Emacs Manual), for more details about package loading.

The :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 user-emacs-directory.

For example:

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

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 eval-and-compile (as opposed to eval-when-compile, see Eval During Compile (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:

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

     (use-package ess-site
       :load-path (lambda () (list (ess-site-load-path)))
       :commands R)

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.

To autoload an interactive command, use the :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 :autoload keyword takes the same arguments as :commands, but is used to autoload non-interactive functions. Here is an example:

     (use-package org-crypt
       :autoload org-crypt-use-before-save-magic)

Configuring Packages
********************

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

Using Lisp code for configuring packages
========================================

The most general way to add customizations are the :preface, :init, and :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 use-package declarations.

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

:preface is evaluated first
---------------------------

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

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

 2. Define functions and variables that will be used in an :if test.

Note that whatever is specified within :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 :preface forms, and restrict them to symbol declarations and definitions.

:init is evaluated before loading package
-----------------------------------------

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

:config is evaluated after loading package
------------------------------------------

The :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 (see Loading Packages), this is deferred until after the package has been loaded.

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

When to use :preface, :config and :init?
----------------------------------------

Where possible, it is better to avoid :preface, :config and :init.  Instead, prefer autoloading keywords such as :bind (see Key bindings), :hook (see Hooks), and :mode (see 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:

     (use-package foo
       :init
       (add-hook 'some-hook 'foo-mode))

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

     (use-package foo
       :defer t
       :init
       (add-hook 'some-hook 'foo-mode))

This is better, as foo is now only loaded when it is actually needed (that is, when the hook 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 :hook (see Hooks), which also implies :defer t.  The above is thereby reduced down to:

     (use-package foo
       :hook some-hook)

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

Key bindings
============

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 keymap-local-set, keymap-global-set and various autoloads.  With use-package, you can simplify this using the :bind keyword, as described in this section.

Global keybindings
------------------

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

Using :bind with a single cons
------------------------------

Here is an example of using a single cons:

     (use-package ace-jump-mode
       :bind ("C-." . ace-jump-mode))

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

Using :bind with a list of conses
---------------------------------

Here is an example of using :bind with a list of conses:

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

This binds the three key sequences to the corresponding commands.

Using special keys
------------------

Inside key strings, special keys like TAB or F1--F12 have to be written inside angle brackets, e.g., "C-<up>". Standalone special keys (and some combinations) can be written in square brackets, e.g. [tab] instead of "<tab>".

Examples:

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

Remapping commands
------------------

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

     (use-package unfill
       :bind ([remap fill-paragraph] . unfill-toggle))

What :bind does behind the scenes
---------------------------------

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

     (use-package ace-jump-mode
       :bind ("C-." . ace-jump-mode))

This could be expressed in a much more verbose way with the :commands and :init keywords:

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

Without using even the :commands keyword, we could also write the above like so:

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

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

Key bindings in local keymaps
-----------------------------

Slightly different from binding a key to a keymap, is binding a key within a local keymap that only exists after the package is loaded.  use-package supports this with a :map modifier, taking the local keymap to bind to:

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

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

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

     (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)))

Binding to keymaps
------------------

Normally :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 autoload function.

To handle this case, use-package offers a special, limited variant of :bind called :bind-keymap.  The only difference is that the ``commands'' bound to by :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:

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

Binding to repeat-maps
----------------------

A special case of binding within a local keymap is when that keymap is used by repeat-mode (see Repeating (GNU Emacs Manual)).  These keymaps are usually defined specifically for this.  Using the :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 repeat-map property of each bound command to that map.

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

     (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)))

Specifying :exit inside the scope of :repeat-map will prevent the 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:

     (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)))

Specifying :continue forces setting the repeat-map property (just like not specifying :exit), so the above snippet is equivalent to:

     (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)))

Displaying personal keybindings
-------------------------------

The :bind keyword uses the bind-keys macro from the 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 M-x describe-personal-keybindings to see all keybindings you've set using either the :bind keyword or the bind-keys macro.

Hooks
=====

The :hook keyword allows adding functions to hooks.  It takes one argument of the form HOOKS, specifying one or more functions to add to one or more hooks.  For the purposes of :hook, the name of hook variables should always exclude the -hook suffix. It is appended automatically for you, to save some typing.

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

     (use-package company
       :commands company-mode
       :init
       (add-hook 'prog-mode-hook #'company-mode))

Using :hook, this can be simplified to:

     (use-package company
       :hook (prog-mode . company-mode))

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

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

     (use-package company
       :hook prog-mode)

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

     (use-package company
       :hook (prog-mode text-mode))

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

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

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

One common mistake when using :hook is to forget to omit the -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 prog-mode-hook-hook:

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

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

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

Modes and interpreters
======================

Similar to :bind, you can use :mode and :interpreter to establish a deferred binding within the auto-mode-alist and interpreter-mode-alist variables (see Auto Major Mode (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 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 "\\.rb\\'" (a file with the .rb extension), or when the first line of the file (known as the ``shebang'') matches the string "ruby":

     (use-package ruby-mode
       :mode "\\.rb\\'"
       :interpreter "ruby")

The default 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:

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

Both the :mode and :interpreter keywords also accept a list of regexps:

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

Magic handlers
==============

Similar to :mode and :interpreter, you can also use :magic and :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 magic-mode-alist and magic-fallback-mode-alist (see Auto Major Mode (GNU Emacs Lisp Reference Manual)).  The difference between :magic and :magic-fallback, is that the latter has a lower priority than :mode.

Here is an example:

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

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

User options
============

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

     (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."))

This is better than using setq in a :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 setopt macro that does this for you.)

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

Also note that if you use :custom in a file that you byte-compile, you could have some unexpected results if you later load or require 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 use-package with :custom settings.

Faces
=====

The :custom-face keyword allows customization of package's faces.  Example:

     (use-package eruby-mode
       :custom-face
       (eruby-standard-face ((t (:slant italic)))))

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

     (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))

Hiding minor modes with diminish and delight
============================================

use-package supports the diminish and 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. (When in doubt, you might as well use diminish.)  To use either of them, you must first install the corresponding package from GNU ELPA.

Diminish
--------

When diminish (The diminish package is installable from GNU ELPA.) is installed, you can use the :diminish keyword.  If diminish is not installed, the :diminish keyword does nothing.

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

     (use-package diminish :ensure t)

The optional :ensure t makes sure the package is installed if it isn't already (see Installing packages).

The :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 -mode appended at the end:

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

Delight
-------

When delight (The delight package is installable from GNU ELPA.) is installed, you can use the :delight keyword.  If delight is not installed, the :delight keyword does nothing.

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

     (use-package delight :ensure t)

The optional :ensure t makes sure the package is installed if it isn't already (see Installing packages).

The :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 -mode appended at the end), both of these, or several lists of both. See Mode Line Data (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 foo-mode minor mode in the foo package:

     (use-package foo
       :delight)

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

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

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

     (use-package foo
       :delight '(:eval buffer-file-name))

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

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

Installing packages automatically
*********************************

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

Installing package
==================

The :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:

     (use-package magit
       :ensure t)

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

     (use-package tex
       :ensure auctex)

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

     (require 'use-package-ensure)
     (setq use-package-always-ensure t)

You can override the above setting for a single package by adding :ensure nil to its declaration.

The :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 see Fetching Package Sources (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 :rev keyword, which has the same shape as the REV argument to package-vc-install.  Notably -- even when not specified -- :rev defaults to checking out the last release of the package. You can use :rev :newest to check out the latest commit.  Note that currently, you cannot upgrade built-in packages using :vc.

For example,

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

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

Alternatively, the use-package-vc-prefer-newest user option exists to always prefer the latest commit.

The :vc keyword can also be used for local packages, by combining it with :load-path (see Load path):

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

The above dispatches to package-vc-install-from-checkout.

Pinning packages using :pin
===========================

use-package can pin a package to a specific archive using the :pin keyword. (The :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 GNU ELPA or NonGNU ELPA (indicated by gnu and nongnu, respectively), while installing specific packages from third-party archives.

For example:

     (use-package company
       :ensure t
       :pin gnu)   ; GNU ELPA

Unfortunately, the third-party archive 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 use-package-always-pin to 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.

If you want to manually keep a package updated and ignore upstream updates, you can pin it to manual.  This will work as long as you have not customized a repository to use that name in the package-archives variable.

Example:

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

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

Non-standard package managers
=============================

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

However, some users might prefer to use a third-party package manager for a specific circumstance or use case.  By setting the user option use-package-ensure-function to the name of a function, you can direct :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.

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.

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.

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

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

If you need to silence a missing function warning, you can use :functions:

     (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))

Normally, 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 use-package for is to add a configuration to the eval-after-load hook.  In such cases, use the :no-require keyword:

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

Troubleshooting
***************

If an error occurs while initializing or configuring a package, this will not stop your Emacs from loading.  Instead, use-package captures the error and reports it in a special *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 --debug-init command line flag.  See Initial Options (GNU Emacs Manual).  To get even more information when using that flag, add the following to your init file (these options are documented below):

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

Since 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 M-x pp-macroexpand-last-sexp, or wrap the use-package declaration in macroexpand and evaluate it.  It is a good idea to include their output in any bugs you file for use-package.

Options that help when troubleshooting
======================================

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 use-package-expand-minimally to a non-nil value to disable this checking.

This behavior may be overridden locally using the :catch keyword.  If t or 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 condition-case).  For example:

     (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))))

Evaluating the above form will print these messages:

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

Gathering Statistics
====================

When a package is loaded, and if you have use-package-verbose set to 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 *Messages* buffer.  The same will happen for configuration, or :config blocks, that take longer than 0.1 seconds to execute.

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 use-package-compute-statistics to a non-nil value.  Then reload your packages, normally by restarting Emacs, to make sure that use-package can gather statistics for all your packages.

Run the command 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 S, or click the column name at the top of the buffer on graphical displays.

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

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

Disabling a package
===================

The :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 foo package:

     (use-package foo
       :disabled)

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

Keyword extensions
******************

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 use-package, and can be optionally enabled.

:use-package-ensure-system-package
==================================

The :ensure-system-package keyword allows you to ensure certain executables are available on your system alongside your package declarations. (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 (https://github.com/purcell/exec-path-from-shell) package.)

To use this extension, add this immediately after loading use-package:

     (use-package use-package-ensure-system-package)

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

     (use-package foo
       :ensure-system-package foo)

This will expect a global binary package to exist called 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 GNU ELPA package system-packages (https://gitlab.com/jabranham/system-packages), so for this to work you must install that first.

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

     (use-package system-packages
       :ensure t)

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

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

     (use-package foo
       :ensure-system-package
       (foocmd . foo))

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

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

     (use-package tern
       :ensure-system-package (tern . "npm i -g tern"))

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

     (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")))

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:

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

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

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

How to create an extension keyword
==================================

This section describes how to create a new keyword.

 1. Add the keyword.

     The first step is to add your keyword at the right place in 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.

 2. Create a normalizer.

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

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

          (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)"))))))

 3. 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 state plist before recursively processing the remaining keywords, to influence keywords that pay attention to the state (one example is the state keyword :deferred, not to be confused with the use-package keyword :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 list of forms representing code to be inserted.  It does not need to be a progn list, as this is handled automatically in other places. Thus it is common to see the idiom of using 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 use-package expansion.

     This is an example handler:

          (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))))))

 4. Test it.

     After the keyword has been inserted into 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 M-x pp-macroexpand-last-sexp with the cursor set immediately after the (use-package ...) expression.

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 README.

GNU Free Documentation License
******************************

     [file doclicense.texi not included]