"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:
- Installs packages asynchronously, in parallel for fast, non-blocking installations.
- Includes a flexible UI for finding and operating on packages.
- Downloads packages from their sources for convenient elisp development.
- Supports thousands of elisp packages out of the box (MELPA, NonGNU/GNU ELPA, Org/org-contrib).
- Makes it easy for users to create their own ELPAs.
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.
Elpaca requires:
- Emacs >= 27.1
- git (minimum version TBD)
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.6)
(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 "elpaca-test.el" (:exclude "extensions"))
:build (:not elpaca--activate-package)))
(let* ((repo (expand-file-name "elpaca/" elpaca-repos-directory))
(build (expand-file-name "elpaca/" elpaca-builds-directory))
(order (cdr elpaca-order))
(default-directory repo))
(add-to-list 'load-path (if (file-exists-p build) build repo))
(unless (file-exists-p repo)
(make-directory repo t)
(when (< emacs-major-version 28) (require 'subr-x))
(condition-case-unless-debug err
(if-let ((buffer (pop-to-buffer-same-window "*elpaca-bootstrap*"))
((zerop (call-process "git" nil buffer t "clone"
(plist-get order :repo) 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)")))
((require 'elpaca))
((elpaca-generate-autoloads "elpaca" repo)))
(progn (message "%s" (buffer-string)) (kill-buffer buffer))
(error "%s" (with-current-buffer buffer (buffer-string))))
((error) (warn "%s" err) (delete-directory repo 'recursive))))
(unless (require 'elpaca-autoloads nil t)
(require 'elpaca)
(elpaca-generate-autoloads "elpaca" repo)
(load "./elpaca-autoloads")))
(add-hook 'after-init-hook #'elpaca-process-queues)
(elpaca `(,@elpaca-order))- Windows users must be able to create symlinks1, or enable
elpaca-no-symlink-mode
;; Uncomment for systems which cannot create symlinks:
;; (elpaca-no-symlink-mode)You'll also want to disable package.el in your early-init file2:
(setq package-enable-at-startup nil)And remove anything related to package.el in your init file. e.g. calls to (package-activate-all).
| Operation | UI (keys apply in elpaca-ui-mode) | completing-read interface commands |
|---|---|---|
| Finding Packages | g m (or M-x elpaca-manager) |
elpaca-info |
| Trying Packages (for current session) | i x |
elpaca-try |
| Fetching Package Updates | f x |
elpaca-fetch or elpaca-fetch-all |
| Merging Updates | m x |
elpaca-merge or elpaca-merge-all |
| Updating Packages* | p x |
elpaca-update or elpaca-update-all |
| Rebuilding Packages | r x |
elpaca-rebuild |
| Deleting Packages | d x |
elpaca-delete |
| View Package Logs | g l |
elpaca-log |
| Visit Package Repository Directory | v |
elpaca-visit |
| Visit Package Build Directory | C-u v |
C-u M-x elpaca-visit |
| Browse Package Website | b |
elpaca-browse |
* Update is an alias for "pull". It's encouraged to fetch, review, and then merge package updates rather than pulling.
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 a package via the elpaca macro
;; See the "recipes" section of the manual for more details.
;; (elpaca example-package)
;; Install use-package support
(elpaca elpaca-use-package
;; Enable use-package :ensure support for Elpaca.
(elpaca-use-package-mode))
;; Block until current queue processed.
(elpaca-wait)
;;When installing a package which modifies a form used at the top-level
;;(e.g. a package which adds a use-package key word),
;;use `elpaca-wait' to block until that package has been installed/configured.
;;For example:
;;(use-package general :ensure t :demand t)
;;(elpaca-wait)
;; Expands to: (elpaca evil (use-package evil :demand t))
(use-package evil :ensure t :demand t)
;;Turns off elpaca-use-package-mode current declaration
;;Note this will cause the declaration to be interpreted immediately (not deferred).
;;Useful for configuring built-in emacs features.
(use-package emacs :ensure 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.3 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. This includes loading of saved customizations. e.g.
(setq custom-file (expand-file-name "customs.el" user-emacs-directory))
(add-hook 'elpaca-after-init-hook (lambda () (load custom-file 'noerror)))3 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.