Reference for Emacs use-package macro

emacs-reference-use-package.org

Reference for Emacs use-package macro

:init

Execute code before a package is loaded

• Accepts one or more forms, up to the next keyword.
• Example

  (use-package foo
    :init
    (setq foo-variable t))
          

:config

Execute code after a package is loaded

• Example

  (use-package foo
    :config
    (foo-mode 1))
          

:custom

Customize package custom variables

• Example

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

:bind

Bind a key to primary commands within a module

• Takes either a cons or a list of conses.
• Example

  (use-package helm
    :bind (("M-x" . helm-M-x)
           ("M-<f5>" . helm-find-files)
           ([f10] . helm-buffers-list)
           ([S-f10] . helm-recentf)))
  
  (use-package helm
    :bind (:map helm-command-map
           ("C-c h" . helm-execute-persistent-action)))
          

:hook

Add functions onto package hooks

• Examples

  (use-package ace-jump-mode
    :hook prog-mode)
  
  (use-package ace-jump-mode
    :hook (prog-mode text-mode))
          

:disabled

Turn off a module

• Example

  (use-package foo
    :disabled)
          

:demand

Override package deferral

• Forces immediate loading even with :bind.
• Example

  (use-package foo
    :demand t)
          

:mode

Specify mode for file names that match regular expressions

• Example

  (use-package jinja2-mode
    :mode "\\.js2")
  
  (use-package yaml-mode
    :mode (("\\.yaml\\'" . yaml-mode)
           ("\\.yml\\'" . yaml-mode)))