Note: This readme's tables of contents are generated with org-make-toc https://github.com/alphapapa/org-make-toc.

[[logo/quelpa-logo-h64.png]]

[[https://github.com/quelpa/quelpa/actions][file:https://github.com/quelpa/quelpa/workflows/CI/badge.svg]] [[https://melpa.org/#/quelpa][file:https://melpa.org/packages/quelpa-badge.svg]] [[https://stable.melpa.org/#/quelpa][file:https://stable.melpa.org/packages/quelpa-badge.svg]]

Build and install your Emacs Lisp packages on-the-fly and directly from source.

• News

• 2022/09/26: Support elpa-devel version scheme (e.x, =0.27.0.20220914.164819=) with =:version-type elpa= in recipes
• 2021/03/12: Switch default from shallow clone to partial clone for git recipes

• Contents :PROPERTIES: :TOC: :include siblings :depth 1 :ignore this :force depth :END: :CONTENTS:

• [[#overview][Overview]]
• [[#requirements][Requirements]]
• [[#installation][Installation]]
• [[#usage][Usage]]
• [[#why-quelpa][Why "Quelpa"?]] :END:

• Overview

=quelpa= is a tool to compile and install Emacs Lisp packages locally from local or remote source code.

Given a recipe in [[https://github.com/melpa/melpa#recipe-format][MELPA's format]], for example:

#+BEGIN_EXAMPLE elisp (quelpa '(hydra :repo "abo-abo/hydra" :fetcher github)) #+END_EXAMPLE

=quelpa= gets the package source code, builds an ELPA compatible package and installs that locally with =package.el=. The installed packages can then be managed in the usual way with =M-x list-packages=.

=quelpa= can be used in many ways, for example to manage your personal packages, testing development versions of other packages or as a helper when developing a package to test building, compiling and installing it.

To get an idea how to use it to manage your Emacs setup, take a look at the [[https://framagit.org/steckerhalter/steckemacs.el][steckemacs configuration]], which uses [[https://github.com/quelpa/quelpa-use-package][quelpa-use-package]] to integrate with =use-package=.

You can build and install packages from (fetcher names in parens): Git (=git=), GitHub (=github=), Bazaar (=bzr=), Mercurial (=hg=), Subversion (=svn=), CVS (=cvs=), Darcs (=darcs=), Fossil (=fossil=) and EmacsWiki (=wiki=)

• Requirements

• Emacs 25.1
• tar
• git (recommend version >= 2.20): [[http://git-scm.com/]]

Every build requires the corresponding build tool. To install a =subversion= hosted package, you need to have =subversion= installed.

Note: Even if the sources of a package are fetched with a VCS tool you have installed, they might have dependencies that require a different VCS tool. Better install the most common ones before proceeding.

• Installation :PROPERTIES: :TOC: :include descendants :depth 1 :END:

You may install =quelpa= like this:

• Using [[https://github.com/melpa/melpa#usage][MELPA]], run =M-x package-install RET quelpa RET=.
• Alternatively, place file =quelpa.el= into a directory in your Emacs =load-path=, then use ~(require 'quelpa)~ in your init file.
• If you want to bootstrap =quelpa= automatically from your init file, you can use this snippet:

#+BEGIN_SRC elisp (unless (package-installed-p 'quelpa) (with-temp-buffer (url-insert-file-contents "https://raw.githubusercontent.com/quelpa/quelpa/master/quelpa.el") (eval-buffer) (quelpa-self-upgrade))) #+END_SRC

• Usage :PROPERTIES: :TOC: :include descendants :depth 1 :END:

Cool. Now that we are all setup, enjoy the ride.

:CONTENTS:

• [[#installing-packages][Installing packages]]
• [[#upgrading-packages][Upgrading packages]]
• [[#managing-packages][Managing packages]]
• [[#using-tagged-versions][Using tagged versions]]
• [[#additional-recipe-fetchers][Additional recipe fetchers]]
• [[#additional-options][Additional options]] :END:

** Installing packages

There are two ways to install packages with Quelpa:

**** By package name

• Interactively, use =M-x quelpa RET=, then input a package name with completion.
• In Lisp code, use ~(quelpa 'package-name)~.

This will fetch the package's source code from its repository, build the package, and install it.

**** By recipe

You can also install packages that are not on MELPA by providing a recipe in the proper [[https://github.com/melpa/melpa/#recipe-format][format]]. For example, call =quelpa= with a recipe like:

#+BEGIN_SRC elisp (quelpa '(discover-my-major :fetcher git :url "https://framagit.org/steckerhalter/discover-my-major.git")) #+END_SRC

Once you installed a package with its own recipe, Quelpa will remember it and next time it can offer you to upgrade/install the package again with =M-x quelpa RET=.

** Upgrading packages

By default, Quelpa does not upgrade installed packages. You can enable upgrading globally by running =M-x customize-variable RET quelpa-upgrade-p RET=.

To override the default and upgrade individual packages:

• Interactively, call =quelpa= with a universal prefix argument, like =C-u M-x quelpa RET=.
• From Lisp, call =quelpa= with the keyword argument =:upgrade=, like ~(quelpa 'package-name :upgrade t)~.
• Interactively, call =M-x quelpa-upgrade RET=, it will list all Quelpa installed packages.

When evaluating a buffer of =quelpa= calls, you may prevent a package from being upgraded by setting =:upgrade nil=, like =(quelpa 'package-name :upgrade nil)=.

*** Upgrading all packages

You may choose to upgrade all Quelpa-installed packages at Emacs startup, but that can slow down Emacs's startup considerably.

Alternatively, you may upgrade all Quelpa-installed packages using =M-x quelpa-upgrade-all RET=. This command relies on the cache file, set in variable =quelpa-cache-file=. It is updated after every =quelpa= invocation.

By default, when upgrading all packages, Quelpa also upgrades itself. Disable this by setting variable =quelpa-self-upgrade-p= to =nil=.

To run =quelpa-upgrade-all= at most every 7 days, after all the init files are loaded:

#+BEGIN_SRC elisp (setq quelpa-upgrade-interval 7) (add-hook #'after-init-hook #'quelpa-upgrade-all-maybe) #+END_SRC

** Managing packages

Quelpa installs packages using Emacs's built-in package library, =package.el=, so after installing a package with Quelpa, you can view its status and remove it using =M-x list-packages RET=. Note that deleting a package this way does not yet affect Quelpa's cache, so Quelpa will still consider the package to have been installed with Quelpa.

Quelpa will automatically remove obsoleted package versions after upgrading. Disable this by setting =quelpa-autoremove-p= to =nil=.

Alternatively, you may prevent a package old version from being removed by setting =:autoremove nil=, like =(quelpa 'foo :autoremove nil)=.

Also, here is the default actions of each Quelpa command related to removing packages:

• =M-x quelpa-upgrade-all=, =M-x quelpa-upgrade=, =C-u M-x quelpa= will by default remove obsoleted packages
• =M-x quelpa= will by default not remove obsoleted package.

** Using tagged versions

Quelpa can be instructed to build tagged versions of packages. This means that the Git or Mercurial repository is queried for a tagged version, and if one is found, that version will be built. For more information please see [[https://github.com/melpa/melpa#stable-packages][MELPA's notes on stable packages]].

To enable building of tagged versions globally, set variable =quelpa-stable-p= to =t=.

To do so for a single package:

• Using the =quelpa= command, use the command's keyword argument =:stable=, like ~(quelpa 'package-name :stable t)~.
• In a package's recipe, use the same keyword, like ~(quelpa '(package-name :stable t))~.

Using the argument to the =quelpa= command overrides the global setting =quelpa-stable-p=, and using the argument in a recipe overrides both the command argument and the global setting.

Note: Non-tagged package version numbers are generated at build time using the current date, and these numbers usually are sorted as higher than tagged version numbers. Therefore, if you have installed a non-tagged package version and wish to replace it with a tagged version, you must first remove the package, then install the tagged version.

Note: Tagged versions are commonly referred to as "stable" versions (since these are the versions appearing in the MELPA Stable repo). However, such package versions are not necessarily more stable than the untagged versions provided in the non-"Stable" MELPA repo, and using them is not generally recommended. Therefore, we do not refer to such versions as "stable" versions.

** Additional recipe fetchers

You may use these additional fetchers in recipes:

*** URL

The =url= fetcher builds packages from single =.el= files. The URL may be a remote HTTP one or a local =file://= one. For example:

#+BEGIN_SRC elisp (quelpa '(rainbow-mode :fetcher url :url "http://git.savannah.gnu.org/cgit/emacs/elpa.git/plain/packages/rainbow-mode/rainbow-mode.el")) #+END_SRC

Note:

• By default, upgrades are managed through file hashes, so if the content has changed, Quelpa will upgrade the package.
• Existing version numbers are retained. Quelpa uses a version suffix that allows the original version to retain priority, so if you install a package from another source with the same version, it will be preferred.
  • To omit the Quelpa-specific version suffix, use the parameter =:version original=. For example:

#+BEGIN_SRC elisp (quelpa '(queue :version original :fetcher url :url "http://www.dr-qubit.org/download.php?file=predictive/queue.el" )) #+END_SRC

*** File

The =file= fetcher builds single-file packages from local =.el= files. For example:

#+BEGIN_SRC elisp (quelpa '(rainbow-mode :fetcher file :path "/home/user/src/rainbow-mode/rainbow-mode.el")) #+END_SRC

It also builds multi-file packages from a local directory. For example:

#+BEGIN_SRC elisp (quelpa '(rainbow-mode :fetcher file :path "~/src/rainbow-mode")) #+END_SRC

Note:

• Specifying