{"id":13471364,"url":"https://github.com/jwiegley/use-package","last_synced_at":"2025-05-14T12:11:40.057Z","repository":{"id":3624755,"uuid":"4690846","full_name":"jwiegley/use-package","owner":"jwiegley","description":"A use-package declaration for simplifying your .emacs","archived":false,"fork":false,"pushed_at":"2024-02-01T20:16:35.000Z","size":2195,"stargazers_count":4452,"open_issues_count":92,"forks_count":260,"subscribers_count":92,"default_branch":"master","last_synced_at":"2025-04-11T04:59:41.755Z","etag":null,"topics":["autoload","deferred-loading","emacs","emacs-lisp","handler","keymap","keyword","melpa"],"latest_commit_sha":null,"homepage":"https://jwiegley.github.io/use-package","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jwiegley.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-06-17T09:40:51.000Z","updated_at":"2025-04-09T11:42:27.000Z","dependencies_parsed_at":"2023-02-17T22:30:41.661Z","dependency_job_id":"5e368ca8-21e0-4684-b1e8-bfb0aa101da3","html_url":"https://github.com/jwiegley/use-package","commit_stats":{"total_commits":741,"total_committers":123,"mean_commits":6.024390243902439,"dds":0.5452091767881242,"last_synced_commit":"77945e002f11440eae72d8730d3de218163d551e"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwiegley%2Fuse-package","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwiegley%2Fuse-package/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwiegley%2Fuse-package/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwiegley%2Fuse-package/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jwiegley","download_url":"https://codeload.github.com/jwiegley/use-package/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254140768,"owners_count":22021220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autoload","deferred-loading","emacs","emacs-lisp","handler","keymap","keyword","melpa"],"created_at":"2024-07-31T16:00:43.686Z","updated_at":"2025-05-14T12:11:40.016Z","avatar_url":"https://github.com/jwiegley.png","language":"Emacs Lisp","funding_links":[],"categories":["Emacs Lisp","emacs"],"sub_categories":[],"readme":"# `use-package`\n\n[![Join the chat at https://gitter.im/use-package/Lobby](https://badges.gitter.im/use-package/Lobby.svg)](https://gitter.im/use-package/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n[![Build Status](https://github.com/jwiegley/use-package/actions/workflows/test.yml/badge.svg)](https://github.com/jwiegley/use-package/actions)\n[![GNU ELPA](https://elpa.gnu.org/packages/use-package.svg)](https://elpa.gnu.org/packages/use-package.html)\n\nThe `use-package` macro allows you to isolate package configuration in your\n`.emacs` file in a way that is both performance-oriented and, well, tidy.  I\ncreated it because I have over 80 packages that I use in Emacs, and things\nwere getting difficult to manage.  Yet with this utility my total load time is\naround 2 seconds, with no loss of functionality!\n\n**NOTE**: `use-package` is **not** a package manager! Although `use-package`\ndoes have the useful capability to interface with package managers (see\n[below](#package-installation)), its primary purpose is for the configuration\nand loading of packages.\n\n- [Installing use-package](#installing-use-package)\n- [Getting started](#getting-started)\n- [Key-binding](#key-binding)\n\t+ [Binding to keymaps](#binding-to-keymaps)\n\t+ [Binding within local keymaps](#binding-within-local-keymaps)\n- [Modes and interpreters](#modes-and-interpreters)\n- [Magic handlers](#magic-handlers)\n- [Hooks](#hooks)\n- [Package customization](#package-customization)\n  + [Customizing variables](#customizing-variables)\n  + [Customizing faces](#customizing-faces)\n- [Notes about lazy loading](#notes-about-lazy-loading)\n- [Information about package loads](#information-about-package-loads)\n- [Conditional loading](#conditional-loading)\n\t+ [Conditional loading before :preface](#conditional-loading-before-preface)\n\t+ [Loading packages in a sequence](#loading-packages-in-sequence)\n\t+ [Prevent loading if dependencies are missing](#prevent-loading-if-dependencies-are-missing)\n- [Byte compiling your .emacs](#byte-compiling-your-emacs)\n\t+ [Prevent a package from loading at compile-time](#prevent-a-package-from-loading-at-compile-time)\n- [Extending the load-path](#extending-the-load-path)\n- [Catching errors during use-package expansion](#catching-errors-during-use-package-expansion)\n- [Diminishing and delighting minor modes](#diminishing-and-delighting-minor-modes)\n- [Package installation](#package-installation)\n\t+ [Usage with other package managers](#usage-with-other-package-managers)\n- [Gathering Statistics](#gathering-statistics)\n- [Keyword Extensions](#keyword-extensions)\n\t+ [use-package-ensure-system-package](#use-package-ensure-system-package)\n\t+ [use-package-chords](#use-package-chords)\n\t+ [How to create an extension](#how-to-create-an-extension)\n\t\t+ [First step: Add the keyword](#first-step-add-the-keyword)\n\t\t+ [Second step: Create a normalizer](#second-step-create-a-normalizer)\n\t\t+ [Third step: Create a handler](#third-step-create-a-handler)\n\t\t+ [Fourth step: Test it out](#fourth-step-test-it-out)\n- [Some timing results](#some-timing-results)\n* [Upgrading to 2.x](#upgrading-to-2x)\n\t+ [Semantics of :init is now consistent](#semantics-of-init-is-now-consistent)\n\t+ [:idle has been removed](#idle-has-been-removed)\n\t+ [:defer now accepts an optional numeric argument](#defer-now-accepts-an-optional-numeric-argument)\n\t+ [Add :preface, occurring before everything except :disabled](#add-preface-occurring-before-everything-except-disabled)\n\t+ [Add :functions, for declaring functions to the byte-compiler](#add-functions-for-declaring-functions-to-the-byte-compiler)\n\t+ [use-package.el is no longer needed at runtime](#use-packageel-is-no-longer-needed-at-runtime)\n## Installing use-package\n\nEither clone from this GitHub repository or install from\n[GNU ELPA](https://elpa.gnu.org/) (recommended).\n\n## Getting started\n\nHere is the simplest `use-package` declaration:\n\n``` elisp\n;; This is only needed once, near the top of the file\n(eval-when-compile\n  ;; Following line is not needed if use-package.el is in ~/.emacs.d\n  (add-to-list 'load-path \"\u003cpath where use-package is installed\u003e\")\n  (require 'use-package))\n\n(use-package foo)\n```\n\nThis loads in the package `foo`, but only if `foo` is available on your\nsystem. If not, a warning is logged to the `*Messages*` buffer.\n\nUse the `:init` keyword to execute code before a package is loaded.  It\naccepts one or more forms, up to the next keyword:\n\n``` elisp\n(use-package foo\n  :init\n  (setq foo-variable t))\n```\n\nSimilarly, `:config` can be used to execute code after a package is loaded.\nIn cases where loading is done lazily (see more about autoloading below), this\nexecution is deferred until after the autoload occurs:\n\n``` elisp\n(use-package foo\n  :init\n  (setq foo-variable t)\n  :config\n  (foo-mode 1))\n```\n\nAs you might expect, you can use `:init` and `:config` together:\n\n``` elisp\n(use-package color-moccur\n  :commands (isearch-moccur isearch-all)\n  :bind ((\"M-s O\" . moccur)\n         :map isearch-mode-map\n         (\"M-o\" . isearch-moccur)\n         (\"M-O\" . isearch-moccur-all))\n  :init\n  (setq isearch-lazy-highlight t)\n  :config\n  (use-package moccur-edit))\n```\n\nIn this case, I want to autoload the commands `isearch-moccur` and\n`isearch-all` from `color-moccur.el`, and bind keys both at the global level\nand within the `isearch-mode-map` (see next section).  When the package is\nactually loaded (by using one of these commands), `moccur-edit` is also\nloaded, to allow editing of the `moccur` buffer.\n\nIf you autoload non-interactive function, please use `:autoload`.\n\n```elisp\n(use-package org-crypt\n  :autoload org-crypt-use-before-save-magic)\n```\n\n## Key-binding\n\nAnother common thing to do when loading a module is to bind a key to primary\ncommands within that module:\n\n``` elisp\n(use-package ace-jump-mode\n  :bind (\"C-.\" . ace-jump-mode))\n```\n\nThis does two things: first, it creates an autoload for the `ace-jump-mode`\ncommand and defers loading of `ace-jump-mode` until you actually use it.\nSecond, it binds the key `C-.` to that command.  After loading, you can use\n`M-x describe-personal-keybindings` to see all such keybindings you've set\nthroughout your `.emacs` file.\n\nA more literal way to do the exact same thing is:\n\n``` elisp\n(use-package ace-jump-mode\n  :commands ace-jump-mode\n  :init\n  (bind-key \"C-.\" 'ace-jump-mode))\n```\n\nWhen you use the `:commands` keyword, it creates autoloads for those commands\nand defers loading of the module until they are used.  Since the `:init` form\nis always run -- even if `ace-jump-mode` might not be on your system --\nremember to restrict `:init` code to only what would succeed either way.\n\nThe `:bind` keyword takes either a cons or a list of conses:\n\n``` elisp\n(use-package hi-lock\n  :bind ((\"M-o l\" . highlight-lines-matching-regexp)\n         (\"M-o r\" . highlight-regexp)\n         (\"M-o w\" . highlight-phrase)))\n```\n\nAlternatively, the command name may be replaced with a cons `(desc . command)`,\nwhere `desc` is a string describing `command`, which is the name of a command\nto bind to:\n\n```elisp\n(use-package avy\n  :bind (\"C-:\" (\"Jump to char\" . avy-goto-char)\n         \"M-g f\" (\"Jump to line\" . avy-goto-line)))\n```\n\nThese descriptions can be used by other code that deals with key bindings.\nFor example, the GNU ELPA package which-key displays them when showing key\nbindings, instead of the plain command names.\n\nThe `:commands` keyword takes either a symbol or a list of symbols.\n\n**NOTE**: inside strings, special keys like `tab` or `F1`-`Fn` have to be written inside angle brackets, e.g. `\"C-\u003cup\u003e\"`.\nStandalone special keys (and some combinations) can be written in square brackets, e.g. `[tab]` instead of `\"\u003ctab\u003e\"`. The syntax for the keybindings is similar to\nthe \"kbd\" syntax: see [https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html](https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html)\nfor more information.\n\nExamples:\n\n``` elisp\n(use-package helm\n  :bind ((\"M-x\" . helm-M-x)\n         (\"M-\u003cf5\u003e\" . helm-find-files)\n         ([f10] . helm-buffers-list)\n         ([S-f10] . helm-recentf)))\n```\n\nFurthermore, [remapping commands](https://www.gnu.org/software/emacs/manual/html_node/elisp/Remapping-Commands.html)\nwith `:bind` and `bind-key` works as expected, because when the\nbinding is a vector, it is passed straight to `define-key`. So the\nfollowing example will rebind `M-q` (originally `fill-paragraph`) to\n`unfill-toggle`:\n\n``` elisp\n(use-package unfill\n  :bind ([remap fill-paragraph] . unfill-toggle))\n```\n\n### Binding to keymaps\n\nNormally `:bind` expects that commands are functions that will be autoloaded\nfrom the given package. However, this does not work if one of those commands\nis actually a keymap, since keymaps are not functions, and cannot be\nautoloaded using Emacs' `autoload` mechanism.\n\nTo handle this case, `use-package` offers a special, limited variant of\n`:bind` called `:bind-keymap`. The only difference is that the \"commands\"\nbound to by `:bind-keymap` must be keymaps defined in the package, rather than\ncommand functions. This is handled behind the scenes by generating custom code\nthat loads the package containing the keymap, and then re-executes your\nkeypress after the first load, to reinterpret that keypress as a prefix key.\n\nFor example:\n\n``` elisp\n(use-package projectile\n  :bind-keymap\n  (\"C-c p\" . projectile-command-map))\n```\n\n### Binding within local keymaps\n\nSlightly different from binding a key to a keymap, is binding a key *within* a\nlocal keymap that only exists after the package is loaded.  `use-package`\nsupports this with a `:map` modifier, taking the local keymap to bind to:\n\n``` elisp\n(use-package helm\n  :bind (:map helm-command-map\n         (\"C-c h\" . helm-execute-persistent-action)))\n```\n\nThe effect of this statement is to wait until `helm` has loaded, and then to\nbind the key `C-c h` to `helm-execute-persistent-action` within Helm's local\nkeymap, `helm-command-map`.\n\nMultiple uses of `:map` may be specified. Any binding occurring before the\nfirst use of `:map` are applied to the global keymap:\n\n``` elisp\n(use-package term\n  :bind ((\"C-c t\" . term)\n         :map term-mode-map\n         (\"M-p\" . term-send-up)\n         (\"M-n\" . term-send-down)\n         :map term-raw-map\n         (\"M-o\" . other-window)\n         (\"M-p\" . term-send-up)\n         (\"M-n\" . term-send-down)))\n```\n### Binding to repeat-maps\n\nA special case of binding within a local keymap is when that keymap is\nused by `repeat-mode`. These keymaps are usually defined specifically\nfor this. Using the `:repeat-map` keyword, and passing it a name for\nthe map it defines, will bind all following keys inside that map, and\n(by default) set the `repeat-map` property of each bound command to\nthat map.\n\n\nThis creates a keymap called `git-gutter+-repeat-map`, makes four\nbindings in it as above, then sets the `repeat-map` property of each\nbound command (`git-gutter+-next-hunk` `git-gutter+-previous-hunk`,\n`git-gutter+-stage-hunks` and `git-gutter+-revert-hunk`) to that\nkeymap.\n\n``` elisp\n(use-package git-gutter+\n  :bind\n  (:repeat-map git-gutter+-repeat-map\n   (\"n\" . git-gutter+-next-hunk)\n   (\"p\" . git-gutter+-previous-hunk)\n   (\"s\" . git-gutter+-stage-hunks)\n   (\"r\" . git-gutter+-revert-hunk)))\n```\n\nSpecifying `:exit` inside the scope of `:repeat-map` will prevent the\n`repeat-map` property being set, so that the command can be used from\nwithin the repeat map, but after it using it the repeat map will no\nlonger be available. This is useful for commands often used at the end\nof a series of repeated commands:\n\n``` elisp\n(use-package git-gutter+\n  :bind\n  (:repeat-map my/git-gutter+-repeat-map\n   (\"n\" . git-gutter+-next-hunk)\n   (\"p\" . git-gutter+-previous-hunk)\n   (\"s\" . git-gutter+-stage-hunks)\n   (\"r\" . git-gutter+-revert-hunk)\n   :exit\n   (\"c\" . magit-commit-create)\n   (\"C\" . magit-commit)\n   (\"b\" . magit-blame)))\n```\n\nSpecifying `:continue` *forces* setting the `repeat-map` property\n(just like *not* specifying `:exit`), so these two snippets are\nequivalent:\n\n``` elisp\n(use-package git-gutter+\n  :bind\n  (:repeat-map my/git-gutter+-repeat-map\n   (\"n\" . git-gutter+-next-hunk)\n   (\"p\" . git-gutter+-previous-hunk)\n   (\"s\" . git-gutter+-stage-hunks)\n   (\"r\" . git-gutter+-revert-hunk)\n   :exit\n   (\"c\" . magit-commit-create)\n   (\"C\" . magit-commit)\n   (\"b\" . magit-blame)))\n```\n\n``` elisp\n(use-package git-gutter+\n  :bind\n  (:repeat-map my/git-gutter+-repeat-map\n   :exit\n   (\"c\" . magit-commit-create)\n   (\"C\" . magit-commit)\n   (\"b\" . magit-blame)\n   :continue\n   (\"n\" . git-gutter+-next-hunk)\n   (\"p\" . git-gutter+-previous-hunk)\n   (\"s\" . git-gutter+-stage-hunks)\n   (\"r\" . git-gutter+-revert-hunk)))\n```\n   \n\n\n\n## Modes and interpreters\n\nSimilar to `:bind`, you can use `:mode` and `:interpreter` to establish a\ndeferred binding within the `auto-mode-alist` and `interpreter-mode-alist`\nvariables. The specifier to either keyword can be a cons cell, a list of cons\ncells, or a string or regexp:\n\n``` elisp\n(use-package ruby-mode\n  :mode \"\\\\.rb\\\\'\"\n  :interpreter \"ruby\")\n\n;; The package is \"python\" but the mode is \"python-mode\":\n(use-package python\n  :mode (\"\\\\.py\\\\'\" . python-mode)\n  :interpreter (\"python\" . python-mode))\n```\n\nIf you aren't using `:commands`, `:bind`, `:bind*`, `:bind-keymap`,\n`:bind-keymap*`, `:mode`, `:interpreter`, or `:hook` (all of which imply `:defer`; see\nthe docstring for `use-package` for a brief description of each), you can\nstill defer loading with the `:defer` keyword:\n\n``` elisp\n(use-package ace-jump-mode\n  :defer t\n  :init\n  (autoload 'ace-jump-mode \"ace-jump-mode\" nil t)\n  (bind-key \"C-.\" 'ace-jump-mode))\n```\n\nThis does exactly the same thing as the following:\n\n``` elisp\n(use-package ace-jump-mode\n  :bind (\"C-.\" . ace-jump-mode))\n```\n\n## Magic handlers\n\nSimilar to `:mode` and `:interpreter`, you can also use `:magic` and\n`:magic-fallback` to cause certain function to be run if the beginning of a\nfile matches a given regular expression. The difference between the two is\nthat `:magic-fallback` has a lower priority than `:mode`. For example:\n\n``` elisp\n(use-package pdf-tools\n  :load-path \"site-lisp/pdf-tools/lisp\"\n  :magic (\"%PDF\" . pdf-view-mode)\n  :config\n  (pdf-tools-install :no-query))\n```\n\nThis registers an autoloaded command for `pdf-view-mode`, defers loading of\n`pdf-tools`, and runs `pdf-view-mode` if the beginning of a buffer matches the\nstring `\"%PDF\"`.\n\n## Hooks\n\nThe `:hook` keyword allows adding functions onto package hooks. The\nfollowing are equivalent:\n\n``` elisp\n(use-package company\n  :hook (prog-mode . company-mode))\n\n(use-package company\n  :commands company-mode\n  :init\n  (add-hook 'prog-mode-hook #'company-mode))\n```\n\nAnd likewise, when multiple hooks should be applied, all of the\nfollowing are also equivalent:\n\n``` elisp\n(use-package company\n  :hook ((prog-mode text-mode) . company-mode))\n\n(use-package company\n  :hook ((prog-mode . company-mode)\n         (text-mode . company-mode)))\n\n(use-package company\n  :hook (prog-mode . company-mode)\n  :hook (text-mode . company-mode))\n\n(use-package company\n  :hook\n  (prog-mode . company-mode)\n  (text-mode . company-mode))\n\n(use-package company\n  :commands company-mode\n  :init\n  (add-hook 'prog-mode-hook #'company-mode)\n  (add-hook 'text-mode-hook #'company-mode))\n```\n\nWhen using `:hook`, omit the \"-hook\" suffix if you specify the hook\nexplicitly, as this is appended by default. For example, the following\ncode will not work as it attempts to add to the `prog-mode-hook-hook`\nwhich does not exist:\n\n``` elisp\n;; DOES NOT WORK\n(use-package ace-jump-mode\n  :hook (prog-mode-hook . ace-jump-mode))\n```\n\nIf you do not like this behaviour, set `use-package-hook-name-suffix`\nto nil. By default the value of this variable is \"-hook\".\n\nThe use of `:hook`, as with `:bind`, `:mode`, `:interpreter`, etc., causes the\nfunctions being hooked to implicitly be read as `:commands` (meaning they will\nestablish interactive `autoload` definitions for that module, if not already\ndefined as functions), and so `:defer t` is also implied by `:hook`.\n\n## Package customization\n\n### Customizing variables.\n\nThe `:custom` keyword allows customization of package custom variables.\n\n``` elisp\n(use-package comint\n  :custom\n  (comint-buffer-maximum-size 20000 \"Increase comint buffer size.\")\n  (comint-prompt-read-only t \"Make the prompt read only.\"))\n```\n\nThe documentation string is not mandatory.\n\n**NOTE**: these are only for people who wish to keep customizations with their\naccompanying use-package declarations. Functionally, the only benefit over\nusing `setq` in a `:config` block is that customizations might execute code\nwhen values are assigned.\n\n**NOTE**: The customized values are **not** saved in the Emacs `custom-file`.\nThus you should either use the `:custom` option **or** you should use `M-x\ncustomize-option` which will save customized values in the Emacs `custom-file`.\nDo not use both.\n\n### Customizing faces\n\nThe `:custom-face` keyword allows customization of package custom faces.\n\n``` elisp\n(use-package eruby-mode\n  :custom-face\n  (eruby-standard-face ((t (:slant italic)))))\n\n(use-package example\n  :custom-face\n  (example-1-face ((t (:foreground \"LightPink\"))))\n  (example-2-face ((t (:foreground \"LightGreen\"))) face-defspec-spec))\n\n(use-package zenburn-theme\n  :preface\n  (setq my/zenburn-colors-alist\n        '((fg . \"#DCDCCC\") (bg . \"#1C1C1C\") (cyan . \"#93E0E3\")))\n  :custom-face\n  (region ((t (:background ,(alist-get my/zenburn-colors-alist 'cyan)))))\n  :config\n  (load-theme 'zenburn t))\n```\n\n## Notes about lazy loading\n\nThe keywords `:commands`, et al, provide \"triggers\" that cause a package to be\nloaded when certain events occur. However, if `use-package` cannot determine\nthat any trigger has been declared, it will load the package immediately (when\nEmacs is starting up) unless `:defer t` is given. The presence of triggers can\nbe overridden using `:demand t` to force immediately loading anyway. For\nexample, `:hook` represents a trigger that fires when the specified hook is\nrun.\n\nIn almost all cases you don't need to manually specify `:defer t`, because\nthis is implied whenever `:bind` or `:mode` or `:interpreter` are used.\nTypically, you only need to specify `:defer` if you know for a fact that some\nother package will do something to cause your package to load at the\nappropriate time, and thus you would like to defer loading even though\n`use-package` has not created any autoloads for you.\n\nYou can override package deferral with the `:demand` keyword. Thus, even if\nyou use `:bind`, adding `:demand` will force loading to occur immediately and\nnot establish an autoload for the bound key.\n\n## Information about package loads\n\nWhen a package is loaded, and if you have `use-package-verbose` set to `t`, or\nif the package takes longer than 0.1s to load, you will see a message to\nindicate this loading activity in the `*Messages*` buffer.  The same will\nhappen for configuration, or `:config` blocks that take longer than 0.1s to\nexecute.  In general, you should keep `:init` forms as simple and quick as\npossible, and put as much as you can get away with into the `:config` block.\nThis way, deferred loading can help your Emacs to start as quickly as\npossible.\n\nAdditionally, if an error occurs while initializing or configuring a package,\nthis will not stop your Emacs from loading.  Rather, the error will be\ncaptured by `use-package`, and reported to a special `*Warnings*` popup\nbuffer, so that you can debug the situation in an otherwise functional Emacs.\n\n## Conditional loading\n\nYou can use the `:if` keyword to predicate the loading and initialization of\nmodules.\n\nFor example, I only want `edit-server` running for my main,\ngraphical Emacs, not for other Emacsen I may start at the command line:\n\n``` elisp\n(use-package edit-server\n  :if window-system\n  :init\n  (add-hook 'after-init-hook 'server-start t)\n  (add-hook 'after-init-hook 'edit-server-start t))\n```\nIn another example, we can load things conditional on the operating system:\n\n``` elisp\n(use-package exec-path-from-shell\n  :if (memq window-system '(mac ns))\n  :ensure t\n  :config\n  (exec-path-from-shell-initialize))\n```\n\nThe `:disabled` keyword can turn off a module you're having difficulties with,\nor stop loading something you're not using at the present time:\n\n``` elisp\n(use-package ess-site\n  :disabled\n  :commands R)\n```\n\nWhen byte-compiling your `.emacs` file, disabled declarations are omitted\nfrom the output entirely, to accelerate startup times.\n\n**NOTE**: `:when` is provided as an alias for `:if`, and `:unless foo` means\nthe same thing as `:if (not foo)`.\n\n### Conditional loading before :preface\n\nIf you need to conditionalize a use-package form so that the condition occurs\nbefore even the `:preface` is executed, simply use `when` around the\nuse-package form itself.  For example, the following will also stop\n`:ensure` from happening on Mac systems:\n\n``` elisp\n(when (memq window-system '(mac ns))\n  (use-package exec-path-from-shell\n    :ensure t\n    :config\n    (exec-path-from-shell-initialize)))\n```\n\n### Loading packages in sequence\n\nSometimes it only makes sense to configure a package after another has been\nloaded, because certain variables or functions are not in scope until that\ntime. This can achieved using an `:after` keyword that allows a fairly rich\ndescription of the exact conditions when loading should occur. Here is an\nexample:\n\n``` elisp\n(use-package hydra\n  :load-path \"site-lisp/hydra\")\n\n(use-package ivy\n  :load-path \"site-lisp/swiper\")\n\n(use-package ivy-hydra\n  :after (ivy hydra))\n```\n\nIn this case, because all of these packages are demand-loaded in the order\nthey occur, the use of `:after` is not strictly necessary. By using it,\nhowever, the above code becomes order-independent, without an implicit\ndepedence on the nature of your init file.\n\nBy default, `:after (foo bar)` is the same as `:after (:all foo bar)`, meaning\nthat loading of the given package will not happen until both `foo` and `bar`\nhave been loaded. Here are some of the other possibilities:\n\n``` elisp\n:after (foo bar)\n:after (:all foo bar)\n:after (:any foo bar)\n:after (:all (:any foo bar) (:any baz quux))\n:after (:any (:all foo bar) (:all baz quux))\n```\n\nWhen you nest selectors, such as `(:any (:all foo bar) (:all baz quux))`, it\nmeans that the package will be loaded when either both `foo` and `bar` have\nbeen loaded, or both `baz` and `quux` have been loaded.\n\n**NOTE**: pay attention if you set `use-package-always-defer` to t, and also use\nthe `:after` keyword, as you will need to specify how the declared package is\nto be loaded: e.g., by some `:bind`. If you're not using one of the mechanisms\nthat registers autoloads, such as `:bind` or `:hook`, and your package manager\ndoes not provide autoloads, it's possible that without adding `:demand t` to\nthose declarations, your package will never be loaded.\n\n### Prevent loading if dependencies are missing\n\nWhile the `:after` keyword delays loading until the dependencies are loaded,\nthe somewhat simpler `:requires` keyword simply never loads the package if the\ndependencies are not available at the time the `use-package` declaration is\nencountered. By \"available\" in this context it means that `foo` is available\nif `(featurep 'foo)` evaluates to a non-nil value. For example:\n\n``` elisp\n(use-package abbrev\n  :requires foo)\n```\n\nThis is the same as:\n\n``` elisp\n(use-package abbrev\n  :if (featurep 'foo))\n```\n\nAs a convenience, a list of such packages may be specified:\n\n``` elisp\n(use-package abbrev\n  :requires (foo bar baz))\n```\n\nFor more complex logic, such as that supported by `:after`, simply use `:if`\nand the appropriate Lisp expression.\n\n## Byte-compiling your .emacs\n\nAnother feature of `use-package` is that it always loads every file that it\ncan when `.emacs` is being byte-compiled.  This helps to silence spurious\nwarnings about unknown variables and functions.\n\nHowever, there are times when this is just not enough.  For those times, use\nthe `:defines` and `:functions` keywords to introduce dummy variable and\nfunction declarations solely for the sake of the byte-compiler:\n\n``` elisp\n(use-package texinfo\n  :defines texinfo-section-list\n  :commands texinfo-mode\n  :init\n  (add-to-list 'auto-mode-alist '(\"\\\\.texi$\" . texinfo-mode)))\n```\n\nIf you need to silence a missing function warning, you can use `:functions`:\n\n``` elisp\n(use-package ruby-mode\n  :mode \"\\\\.rb\\\\'\"\n  :interpreter \"ruby\"\n  :functions inf-ruby-keys\n  :config\n  (defun my-ruby-mode-hook ()\n    (require 'inf-ruby)\n    (inf-ruby-keys))\n\n  (add-hook 'ruby-mode-hook 'my-ruby-mode-hook))\n```\n\n### Prevent a package from loading at compile-time\n\nNormally, `use-package` will load each package at compile time before\ncompiling the configuration, to ensure that any necessary symbols are in scope\nto satisfy the byte-compiler.  At times this can cause problems, since a\npackage may have special loading requirements, and all that you want to use\n`use-package` for is to add a configuration to the `eval-after-load` hook.  In\nsuch cases, use the `:no-require` keyword:\n\n``` elisp\n(use-package foo\n  :no-require t\n  :config\n  (message \"This is evaluated when `foo' is loaded\"))\n```\n\n## Extending the load-path\n\nIf your package needs a directory added to the `load-path` in order to load,\nuse `:load-path`.  This takes a symbol, a function, a string or a list of\nstrings.  If the path is relative, it is expanded within\n`user-emacs-directory`:\n\n``` elisp\n(use-package ess-site\n  :load-path \"site-lisp/ess/lisp/\"\n  :commands R)\n```\n\n**NOTE**: when using a symbol or a function to provide a dynamically generated\nlist of paths, you must inform the byte-compiler of this definition so the\nvalue is available at byte-compilation time.  This is done by using the\nspecial form `eval-and-compile` (as opposed to `eval-when-compile`).  Further,\nthis value is fixed at whatever was determined during compilation, to avoid\nlooking up the same information again on each startup:\n\n``` elisp\n(eval-and-compile\n  (defun ess-site-load-path ()\n    (shell-command \"find ~ -path ess/lisp\")))\n\n(use-package ess-site\n  :load-path (lambda () (list (ess-site-load-path)))\n  :commands R)\n```\n\n## Catching errors during use-package expansion\n\nBy default, if `use-package-expand-minimally` is nil (the default),\nuse-package will attempts to catch and report errors that occur during\nexpansion of use-package declarations in your init file. Setting\n`use-package-expand-minimally` to t completely disables this checking.\n\nThis behavior may be overridden locally using the `:catch` keyword. If `t` or\n`nil`, it enables or disables catching errors at load time. It can also be a\nfunction taking two arguments: the keyword being processed at the time the\nerror was encountered, and the error object (as generated by\n`condition-case`). For example:\n\n``` elisp\n(use-package example\n  ;; Note that errors are never trapped in the preface, since doing so would\n  ;; hide definitions from the byte-compiler.\n  :preface (message \"I'm here at byte-compile and load time.\")\n  :init (message \"I'm always here at startup\")\n  :config\n  (message \"I'm always here after the package is loaded\")\n  (error \"oops\")\n  ;; Don't try to (require 'example), this is just an example!\n  :no-require t\n  :catch (lambda (keyword err)\n           (message (error-message-string err))))\n```\n\nEvaluating the above form will print these messages:\n\n```\nI’m here at byte-compile and load time.\nI’m always here at startup\nConfiguring package example...\nI’m always here after the package is loaded\noops\n```\n\n## Diminishing and delighting minor modes\n\n`use-package` also provides built-in support for the diminish and\ndelight utilities -- if you have them installed. Their purpose is to\nremove or change minor mode strings in your mode-line.\n\n[diminish](https://github.com/myrjola/diminish.el) is invoked with\nthe `:diminish` keyword, which is passed either a minor mode symbol, a\ncons of the symbol and its replacement string, or just a replacement\nstring, in which case the minor mode symbol is guessed to be the\npackage name with \"-mode\" appended at the end:\n\n``` elisp\n(use-package abbrev\n  :diminish abbrev-mode\n  :config\n  (if (file-exists-p abbrev-file-name)\n      (quietly-read-abbrev-file)))\n```\n\n[delight](https://elpa.gnu.org/packages/delight.html) is invoked with\nthe `:delight` keyword, which is passed a minor mode symbol, a\nreplacement string or\nquoted\n[mode-line data](https://www.gnu.org/software/emacs/manual/html_node/elisp/Mode-Line-Data.html) (in\nwhich case the minor mode symbol is guessed to be the package name\nwith \"-mode\" appended at the end), both of these, or several lists of\nboth. If no arguments are provided, the default mode name is hidden\ncompletely.\n\n``` elisp\n;; Don't show anything for rainbow-mode.\n(use-package rainbow-mode\n  :delight)\n\n;; Don't show anything for auto-revert-mode, which doesn't match\n;; its package name.\n(use-package autorevert\n  :delight auto-revert-mode)\n\n;; Remove the mode name for projectile-mode, but show the project name.\n(use-package projectile\n  :delight '(:eval (concat \" \" (projectile-project-name))))\n\n;; Completely hide visual-line-mode and change auto-fill-mode to \" AF\".\n(use-package emacs\n  :delight\n  (auto-fill-function \" AF\")\n  (visual-line-mode))\n```\n\n## Package installation\n\nYou can use `use-package` to load packages from ELPA with `package.el`. This\nis particularly useful if you share your `.emacs` among several machines; the\nrelevant packages are downloaded automatically once declared in your `.emacs`.\nThe `:ensure` keyword causes the package(s) to be installed automatically if\nnot already present on your system:\n\n``` elisp\n(use-package magit\n  :ensure t)\n```\n\nIf you need to install a different package from the one named by\n`use-package`, you can specify it like this:\n\n``` elisp\n(use-package tex\n  :ensure auctex)\n```\n\nEnable `use-package-always-ensure` if you wish this behavior to be global\nfor all packages:\n\n``` elisp\n(require 'use-package-ensure)\n(setq use-package-always-ensure t)\n```\n\n**NOTE**: `:ensure` will install a package if it is not already installed, but\nit does not keep it up-to-date. If you want to keep your packages updated\nautomatically, one option is to use\n[auto-package-update](https://github.com/rranelli/auto-package-update.el),\nlike\n\n``` elisp\n(use-package auto-package-update\n  :config\n  (setq auto-package-update-delete-old-versions t)\n  (setq auto-package-update-hide-results t)\n  (auto-package-update-maybe))\n```\n\nLastly, when running on Emacs 24.4 or later, use-package can pin a package to\na specific archive, allowing you to mix and match packages from different\narchives.  The primary use-case for this is preferring packages from the\n`gnu` and `melpa-stable` archives, but using specific packages from `melpa`\nwhen you need to track newer versions than what is available in the `stable`\narchives is also a valid use-case.\n\nBy default `package.el` prefers `melpa` over `melpa-stable` due to the\nversioning `(\u003e evil-20141208.623 evil-1.0.9)`, so even if you are tracking\nonly a single package from `melpa`, you will need to tag all the non-`melpa`\npackages with the appropriate archive. If this really annoys you, then you can\nset `use-package-always-pin` to set a default.\n\nIf you want to manually keep a package updated and ignore upstream updates,\nyou can pin it to `manual`, which as long as there is no repository by that\nname, will Just Work(tm).\n\n`use-package` throws an error if you try to pin a package to an archive that\nhas not been configured using `package-archives` (apart from the magic\n`manual` archive mentioned above):\n\n```\nArchive 'foo' requested for package 'bar' is not available.\n```\n\nExample:\n\n``` elisp\n(use-package company\n  :ensure t\n  :pin gnu)\n\n(use-package evil\n  :ensure t)\n  ;; no :pin needed, as package.el will choose the version in melpa\n\n(use-package adaptive-wrap\n  :ensure t\n  ;; as this package is available only in the gnu archive, this is\n  ;; technically not needed, but it helps to highlight where it\n  ;; comes from\n  :pin gnu)\n\n(use-package org\n  :ensure t\n  ;; ignore org-mode from upstream and use a manually installed version\n  :pin manual)\n```\n\n**NOTE**: the `:pin` argument has no effect on emacs versions \u003c 24.4.\n\n### Usage with other package managers\n\nBy overriding `use-package-ensure-function` and/or\n`use-package-pre-ensure-function`, other package managers can override\n`:ensure` to use them instead of `package.el`. At the present time,\nthe only package manager that does this\nis [`straight.el`](https://github.com/raxod502/straight.el).\n\n## Gathering Statistics\n\nIf you'd like to see how many packages you've loaded, what stage of\ninitialization they've reached, and how much aggregate time they've\nspent (roughly), you can enable `use-package-compute-statistics` after\nloading `use-package` but before any `use-package` forms, and then run\nthe command `M-x use-package-report` to see the results. The buffer\ndisplayed is a tabulated list. You can use `S` in a column to sort the\nrows based on it.\n\n## Keyword Extensions\n\nStarting with version 2.0, `use-package` is based on an extensible\nframework that makes it easy for package authors to add new keywords,\nor modify the behavior of existing keywords.\n\nSome keyword extensions are now included in the `use-package`\ndistribution and can be optionally installed.\n\n### `(use-package-ensure-system-package)`\n\nThe `:ensure-system-package` keyword allows you to ensure system\nbinaries exist alongside your package declarations.\n\nFirst, you will want to make sure `exec-path` is cognisant of all\nbinary package names that you would like to ensure are\ninstalled. [`exec-path-from-shell`](https://github.com/purcell/exec-path-from-shell)\nis often a good way to do this.\n\nTo enable the extension after you've loaded `use-package`:\n\n``` elisp\n(use-package use-package-ensure-system-package\n  :ensure t)\n```\n\nHere’s an example of usage:\n\n``` emacs-lisp\n(use-package rg\n  :ensure-system-package rg)\n```\n\nThis will expect a global binary package to exist called `rg`. If it\ndoes not, it will use your system package manager (using the package\n[`system-packages`](https://gitlab.com/jabranham/system-packages)) to\nattempt an install of a binary by the same name asynchronously. For\nexample, for most `macOS` users this would call: `brew install rg`.\n\nIf the package is named differently than the binary, you can use a\ncons in the form of  `(binary . package-name)`, i.e.:\n\n``` emacs-lisp\n(use-package rg\n  :ensure-system-package\n  (rg . ripgrep))\n```\n\nIn the previous `macOS` example, this would call: `brew install\nripgrep` if `rg` was not found.\n\nWhat if you want to customize the install command further?\n\n``` emacs-lisp\n(use-package tern\n  :ensure-system-package (tern . \"npm i -g tern\"))\n```\n\n`:ensure-system-package` can also take a cons where its `cdr` is a\nstring that will get called by `(async-shell-command)` to install if\nit isn’t found.\n\nYou may also pass in a list of cons-es:\n\n``` emacs-lisp\n(use-package ruby-mode\n  :ensure-system-package\n  ((rubocop     . \"gem install rubocop\")\n   (ruby-lint   . \"gem install ruby-lint\")\n   (ripper-tags . \"gem install ripper-tags\")\n   (pry         . \"gem install pry\")))\n```\n\nFinally, in case the package dependency does not provide a global\nexecutable, you can ensure packages exist by checking the presence of\na file path by providing a string like so:\n\n``` emacs-lisp\n(use-package dash-at-point\n  :if (eq system-type 'darwin)\n  :ensure-system-package\n  (\"/Applications/Dash.app\" . \"brew cask install dash\"))\n```\n\n`:ensure-system-package` will use `system-packages-install` to install\nsystem packages, except where a custom command has been specified, in\nwhich case it will be executed verbatim by `async-shell-command`.\n\nConfiguration variables `system-packages-package-manager` and\n`system-packages-use-sudo` will be honoured, but not for custom\ncommands. Custom commands should include the call to sudo in the\ncommand if needed.\n\n### `(use-package-chords)`\n\nThe `:chords` keyword allows you to define\n[`key-chord`](http://www.emacswiki.org/emacs/key-chord.el) bindings\nfor `use-package` declarations in the same manner as the `:bind`\nkeyword.\n\nTo enable the extension:\n\n``` elisp\n(use-package use-package-chords\n  :ensure t\n  :config (key-chord-mode 1))\n```\n\nThen you can define your chord bindings in the same manner as `:bind` using a cons or a list of conses:\n\n``` elisp\n(use-package ace-jump-mode\n  :chords ((\"jj\" . ace-jump-char-mode)\n           (\"jk\" . ace-jump-word-mode)\n           (\"jl\" . ace-jump-line-mode)))\n```\n\n### How to create an extension\n\n#### First step: Add the keyword\n\nThe first step is to add your keyword at the right place in\n`use-package-keywords`.  This list determines the order in which things will\nhappen in the expanded code.  You should never change this order, but it gives\nyou a framework within which to decide when your keyword should fire.\n\n#### Second step: Create a normalizer\n\nDefine a normalizer for your keyword by defining a function named after the\nkeyword, for example:\n\n``` elisp\n(defun use-package-normalize/:pin (name-symbol keyword args)\n  (use-package-only-one (symbol-name keyword) args\n    (lambda (label arg)\n      (cond\n       ((stringp arg) arg)\n       ((symbolp arg) (symbol-name arg))\n       (t\n        (use-package-error\n         \":pin wants an archive name (a string)\"))))))\n```\n\nThe job of the normalizer is take a list of arguments (possibly nil), and turn\nit into the single argument (which could still be a list) that should appear\nin the final property list used by `use-package`.\n\n#### Third step: Create a handler\n\nOnce you have a normalizer, you must create a handler for the keyword:\n\n``` elisp\n(defun use-package-handler/:pin (name-symbol keyword archive-name rest state)\n  (let ((body (use-package-process-keywords name-symbol rest state)))\n    ;; This happens at macro expansion time, not when the expanded code is\n    ;; compiled or evaluated.\n    (if (null archive-name)\n        body\n      (use-package-pin-package name-symbol archive-name)\n      (use-package-concat\n       body\n       `((push '(,name-symbol . ,archive-name)\n               package-pinned-packages))))))\n```\n\nHandlers can affect the handling of keywords in two ways.  First, it can\nmodify the `state` plist before recursively processing the remaining keywords,\nto influence keywords that pay attention to the state (one example is the\nstate keyword `:deferred`, not to be confused with the `use-package` keyword\n`:defer`).  Then, once the remaining keywords have been handled and their\nresulting forms returned, the handler may manipulate, extend, or just ignore\nthose forms.\n\nThe task of each handler is to return a *list of forms* representing code to\nbe inserted.  It does not need to be a `progn` list, as this is handled\nautomatically in other places.  Thus it is very common to see the idiom of\nusing `use-package-concat` to add new functionality before or after a code\nbody, so that only the minimum code necessary is emitted as the result of a\n`use-package` expansion.\n\n#### Fourth step: Test it out\n\nAfter the keyword has been inserted into `use-package-keywords`, and a\nnormalizer and a handler defined, you can now test it by seeing how usages of\nthe keyword will expand.  For this, use `M-x pp-macroexpand-last-sexp` with\nthe cursor set immediately after the `(use-package ...)` expression.\n\n## Some timing results\n\nOn my Retina iMac, the \"Mac port\" variant of Emacs 24.4 loads in 0.57s, with\naround 218 packages configured (nearly all of them lazy-loaded).  However, I\nexperience no loss of functionality, just a bit of latency when I'm first\nstarting to use Emacs (due to the autoloading).  Since I also use idle-loading\nfor many packages, perceived latency is typically reduced overall.\n\nOn Linux, the same configuration loads in 0.32s.\n\nIf I don't use Emacs graphically, I can test the absolute minimum times.  This\nis done by running:\n\n``` bash\ntime emacs -l init.elc -batch --eval '(message \"Hello, world!\")'\n```\n\nOn the Mac I see an average of 0.36s for the same configuration, and on Linux\n0.26s.\n\n# Upgrading to 2.x\n\n## Semantics of :init is now consistent\n\nThe meaning of `:init` has been changed: It now *always* happens before\npackage load, whether `:config` has been deferred or not.  This means that\nsome uses of `:init` in your configuration may need to be changed to `:config`\n(in the non-deferred case).  For the deferred case, the behavior is unchanged\nfrom before.\n\nAlso, because `:init` and `:config` now mean \"before\" and \"after\", the `:pre-`\nand `:post-` keywords are gone, as they should no longer be necessary.\n\nLastly, an effort has been made to make your Emacs start even in the presence\nof use-package configuration failures.  So after this change, be sure to check\nyour `*Messages*` buffer.  Most likely, you will have several instances where\nyou are using `:init`, but should be using `:config` (this was the case for me\nin a number of places).\n\n## :idle has been removed\n\nI am removing this feature for now because it can result in a nasty\ninconsistency.  Consider the following definition:\n\n``` elisp\n(use-package vkill\n  :commands vkill\n  :idle (some-important-configuration-here)\n  :bind (\"C-x L\" . vkill-and-helm-occur)\n  :init\n  (defun vkill-and-helm-occur ()\n    (interactive)\n    (vkill)\n    (call-interactively #'helm-occur))\n\n  :config\n  (setq vkill-show-all-processes t))\n```\n\nIf I load my Emacs and wait until the idle timer fires, then this is the\nsequence of events:\n\n    :init :idle \u003cload\u003e :config\n\nBut if I load Emacs and immediately type C-x L without waiting for the idle\ntimer to fire, this is the sequence of events:\n\n    :init \u003cload\u003e :config :idle\n\nIt's possible that the user could use `featurep` in their idle to test for\nthis case, but that's a subtlety I'd rather avoid.\n\n## :defer now accepts an optional numeric argument\n\n`:defer [N]` causes the package to be loaded -- if it has not already been --\nafter `N` seconds of idle time.\n\n``` elisp\n(use-package back-button\n  :commands (back-button-mode)\n  :defer 2\n  :init\n  (setq back-button-show-toolbar-buttons nil)\n  :config\n  (back-button-mode 1))\n```\n\n## Add :preface, occurring before everything except :disabled\n\n`:preface` can be used to establish function and variable definitions that\nwill 1) make the byte-compiler happy (it won't complain about functions whose\ndefinitions are unknown because you have them within a guard block), and 2)\nallow you to define code that can be used in an `:if` test.\n\n**NOTE**: whatever is specified within `:preface` is evaluated both at load\ntime and at byte-compilation time, in order to ensure that definitions are\nseen by both the Lisp evaluator and the byte-compiler, so you should avoid\nhaving any side-effects in your preface, and restrict it merely to symbol\ndeclarations and definitions.\n\n## Add :functions, for declaring functions to the byte-compiler\n\nWhat `:defines` does for variables, `:functions` does for functions.\n\n## use-package.el is no longer needed at runtime\n\nThis means you should put the following at the top of your Emacs, to further\nreduce load time:\n\n``` elisp\n(eval-when-compile\n  (require 'use-package))\n(require 'diminish)                ;; if you use :diminish\n(require 'bind-key)                ;; if you use any :bind variant\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwiegley%2Fuse-package","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjwiegley%2Fuse-package","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwiegley%2Fuse-package/lists"}