Build and install your Emacs Lisp packages on-the-fly and directly from source.
- 2002/09/26: Support elpa-devel version scheme (e.x,
:vertion-type quelpain recipes
- 2021/03/12: Switch default from shallow clone to partial clone for git recipes
- 2020/03/04: Obsoleted packages will automatically be removed when newer package installed successfully
- 2020/03/02: Emacs 24 is not supported anymore, please upgrade to use
- 2020/03/02: BREAKING CHANGE
bootstrap.elhas been deprecated, please change your bootstrapping snippet as documented in the Installation section below.
quelpa is a tool to compile and install Emacs Lisp packages locally from local or remote source code.
Given a recipe in MELPA’s format, for example:
(quelpa '(hydra :repo "abo-abo/hydra" :fetcher github))
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
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.
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 (
- Emacs 25.1
- 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
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.
You may install
quelpa like this:
- Using MELPA, run
M-x package-install RET quelpa RET.
- Alternatively, place file
quelpa.elinto a directory in your Emacs
load-path, then use
(require 'quelpa)in your init file.
- If you want to bootstrap
quelpaautomatically from your init file, you can use this snippet:
(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)))
Cool. Now that we are all setup, enjoy the ride.
- Installing packages
- Upgrading packages
- Managing packages
- Using tagged versions
- Additional recipe fetchers
- Additional options
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
This will fetch the package’s source code from its repository, build the package, and install it.
You can also install packages that are not on MELPA by providing a recipe in the proper format. For example, call
quelpa with a recipe like:
(quelpa '(discover-my-major :fetcher git :url "https://framagit.org/steckerhalter/discover-my-major.git"))
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.
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
quelpawith a universal prefix argument, like
C-u M-x quelpa RET.
- From Lisp, call
quelpawith the keyword argument
(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
By default, when upgrading all packages, Quelpa also upgrades itself. Disable this by setting variable
quelpa-upgrade-all at most every 7 days, after all the init files are loaded:
(setq quelpa-upgrade-interval 7) (add-hook #'after-init-hook #'quelpa-upgrade-all-maybe)
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
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:
C-u M-x quelpawill by default remove obsoleted packages
M-x quelpawill 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 MELPA’s notes on stable packages.
To enable building of tagged versions globally, set variable
To do so for a single package:
- Using the
quelpacommand, use the command’s keyword argument
(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 fetcher builds packages from single
.el files. The URL may be a remote HTTP one or a local
file:// one. For example:
(quelpa '(rainbow-mode :fetcher url :url "http://git.savannah.gnu.org/cgit/emacs/elpa.git/plain/packages/rainbow-mode/rainbow-mode.el"))
- 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:
- To omit the Quelpa-specific version suffix, use the parameter
(quelpa '(queue :version original :fetcher url :url "http://www.dr-qubit.org/download.php?file=predictive/queue.el" ))
file fetcher builds single-file packages from local
.el files. For example:
(quelpa '(rainbow-mode :fetcher file :path "/home/user/src/rainbow-mode/rainbow-mode.el"))
It also builds multi-file packages from a local directory. For example:
(quelpa '(rainbow-mode :fetcher file :path "~/src/rainbow-mode"))
- Specifying a directory for
:pathdoes not retain existing version numbers, nor does it respect the
- Paths are expanded with
~in path names is expanded to the user’s home directory.
github-ssh fetcher builds packages from
github ssh link, it’s alternative of
github fetcher which builds packages from
https link. For example, the following recipe will clone
email@example.com:quelpa/quelpa.git and builds it:
(quelpa '(quelpa :fetcher github-ssh :repo "quelpa/quelpa"))
- You should setup Github ssh key before using this.
- This fetcher will come handy when you want to modify the packages and contribute back without the needs of enter password everytime.
Prevent updating of MELPA repo on Emacs startup
By default, when Quelpa is loaded, it updates the local clone of the MELPA git repo, which ensures that the latest recipes are always available. If you load Quelpa in your init file, this naturally lengthens Emacs’s startup time. You may disable this by setting
quelpa-update-melpa-p to nil before loading Quelpa.
If you don’t want to use MELPA recipes at all (e.g. if you’re using Quelpa mainly to install packages not in MELPA) you can disable all fetching of the MELPA repo by setting
quelpa-checkout-melpa-p to nil.
Use local recipes
You may configure Quelpa to use recipes stored in a local directory in preference to those in MELPA. This may be helpful if you wish to modify a MELPA recipe. The variable
quelpa-melpa-recipe-stores is a list of directory paths which are searched for recipes; by default, it contains the path to the local MELPA clone’s recipes directory. Directories listed in the variable are searched in order, so to give your own recipe directory preference, add it to the front of the list, like:
(add-to-list 'quelpa-melpa-recipe-stores "/home/user/src/recipes")
If a package’s recipe is not found in that directory, Quelpa will fall back on remaining directories in the list, including the MELPA recipe directory.
Recipe files should be named after the package name, without any filename extension.
The German word quelle means spring (as in: water source) but also source. Source code is translated to quellcode. ELPA is the abbreviation for Emacs Lisp Package Archive. You get the idea.