psionic-k / elpaca

An elisp package manager

Elpaca: An Elisp Package Manager

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

Video Tour

Installation

Requirements

Elpaca requires:

• Emacs >= 27.1
• git (minimum version TBD)

Installer

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 symlinks¹, 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 file²:

(setq package-enable-at-startup nil)

And remove anything related to package.el in your init file. e.g. calls to (package-activate-all).

Quick Start

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
Fetching Package Updates	f x	elpaca-fetch or elpaca-fetch-all
Merging Updates	u x	elpaca-merge or elpaca-merge-all
Pulling Updates*	C-u u x	C-u M-x elpaca-merge or C-u M-x elpaca-merge-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 M-x elpaca-visit
Browse Package Website	b	elpaca-browse

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

;;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 :demand t)
;;(elpaca-wait)

;; Expands to: (elpaca evil (use-package evil :demand t))
(use-package evil :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 :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.³ 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)))

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.

Footnotes

¹ windows symlink guide

² early-init file

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