“Chews data, spits packages.”
Elpaca is an elisp package manager. It allows users to find, install, update, and remove third-party packages for Emacs. It is a replacement for the built-in Emacs package manager, package.el.
Elpaca requires:
- Emacs >= 27.1
- git (minimum version TBD)
- Windows users must be able to create symlinks.
To install Elpaca, add the following elisp to your init.el.
It must come before any calls to other Elpaca functions/macros.
This will clone Elpaca into your user-emacs-directory under the elpaca subdirectory.
It then builds and activates Elpaca.
(defvar elpaca-installer-version 0.2)
(defvar elpaca-directory (expand-file-name "elpaca/" user-emacs-directory))
(defvar elpaca-builds-directory (expand-file-name "builds/" elpaca-directory))
(defvar elpaca-repos-directory (expand-file-name "repos/" elpaca-directory))
(defvar elpaca-order '(elpaca :repo "https://github.com/progfolio/elpaca.git"
:ref nil
:files (:defaults (:exclude "extensions"))
:build (:not elpaca--activate-package)))
(when-let ((repo (expand-file-name "elpaca/" elpaca-repos-directory))
(build (expand-file-name "elpaca/" elpaca-builds-directory))
(order (cdr elpaca-order))
((add-to-list 'load-path (if (file-exists-p build) build repo)))
((not (file-exists-p repo))))
(condition-case-unless-debug err
(if-let ((buffer (pop-to-buffer-same-window "*elpaca-installer*"))
((zerop (call-process "git" nil buffer t "clone"
(plist-get order :repo) repo)))
(default-directory repo)
((zerop (call-process "git" nil buffer t "checkout"
(or (plist-get order :ref) "--"))))
(emacs (concat invocation-directory invocation-name))
((zerop (call-process emacs nil buffer nil "-Q" "-L" "." "--batch"
"--eval" "(byte-recompile-directory \".\" 0 'force)"))))
(progn (require 'elpaca)
(elpaca-generate-autoloads "elpaca" repo)
(kill-buffer buffer))
(error "%s" (with-current-buffer buffer (buffer-string))))
((error) (warn "%s" err) (delete-directory repo 'recursive))))
(require 'elpaca-autoloads)
(add-hook 'after-init-hook #'elpaca-process-queues)
(elpaca `(,@elpaca-order))You’ll also want to disable package.el in your early-init file[fn:-0-1]:
(setq package-enable-at-startup nil)And remove anything related to package.el in your init file. e.g. calls to (package-activate-all).
[fn:-0-1] https://www.gnu.org/software/emacs/manual/html_node/emacs/Early-Init-File.html
| Operation | UI (keys apply in elpaca-ui-mode) | completing-read interface commands |
|---|---|---|
| Finding Packages | M-x elpaca-manager | elpaca-try |
| Trying Packages (for current session) | i x | elpaca-try |
| Updating Packages | u x | elpaca-update or M-x elpaca-update-all |
| Rebuilding Packages | r x | elpaca-rebuild |
| Deleting Packages | d x | elpaca-delete |
| View Package Logs | l filters log to current package | elpaca-log |
| View Package Statuses | t show most recent log entries | elpaca-status |
| Visit Package Repository Directory | v | elpaca-visit |
| Visit Package Build Directory | C-u v | C-u elpaca-visit |
| Browse Package Website | b | elpaca-browse |
Packages installed via the above commands are not loaded on subsequent Emacs sessions (after restarting).
To install and load packages persistently (across Emacs restarts), use the elpaca macro in your init file after the installer. (installer)
For example:
;; Install use-package support
(elpaca elpaca-use-package
;; Enable :elpaca use-package keyword.
(elpaca-use-package-mode)
;; Assume :elpaca t unless otherwise specified.
(setq elpaca-use-package-by-default t))
;; Block until current queue processed.
(elpaca-wait)
;; Expands to: (elpaca evil (use-package evil :demand t))
(use-package evil :demand t)
;;Turns off elpaca-use-package-mode current declartion
;;Note this will cause the declaration to be interpreted immediately (not deferred).
;;Useful for configuring built-in emacs features.
(use-package emacs :elpaca nil :config (setq ring-bell-function #'ignore))
;; Don't install anything. Defer execution of BODY
(elpaca nil (message "deferred"))IMPORTANT:
Elpaca installs and activates packages asynchronously. Elpaca processes its package queues after Emacs reads the init file.[fn:-0-2] Consider the following example:
(elpaca nil (message "First")) ; Queue First
(message "Second") ; Second messaged
(elpaca nil (message "Third")) ; Queue Third
(elpaca-process-queues) ; Process queue: First messaged, Third messaged.“Second” will be message before “First” and “Third”.
Defer forms which are dependent on deferred forms.
Wrapping the “Second” message in an elpaca declaration will fix the above example:
(elpaca nil (message "First")) ; Queue First
(elpaca nil (message "Second")) ; Queue Second
(elpaca nil (message "Third")) ; Queue Third
(elpaca-process-queues) ; Process queue: First, Second, Third messaged.Add any configuration which relies on after-init-hook, emacs-startup-hook, etc to elpaca-after-init-hook so it runs after Elpaca has activated all queued packages.
See the manual for in-depth information on Elpaca usage, customization, and development. Users who wish to experiment with Elpaca may find the example init.el and early-init.el files useful.
[fn:-0-2] This is so Elpaca can build a proper dependency tree. It ensures packages the user explicitly requests are not preempted by dependencies of other packages.