Build and install your Emacs Lisp packages on-the-fly and directly from source.
2018/06/18 - code moved to framagit.org, please open issues here (github is only an MS mirror now 8)
2018/03/25 - support for various fetchers has been added again:
- MacOS instructions
- Windows instructions
- Why "quelpa"?
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 24.3.1
- git: 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.
Note: For Windows, see the Instructions for Windows before continuing
quelpa needs to be installed. You can install
quelpa either from MELPA (see https://github.com/melpa/melpa#usage for setup):
M-x package-install RET quelpa RET
or if you are not using MELPA:
(package-initialize) (if (require 'quelpa nil t) (quelpa-self-upgrade) (with-temp-buffer (url-insert-file-contents "https://framagit.org/steckerhalter/quelpa/raw/master/bootstrap.el") (eval-buffer)))
Evaluate this expression in your
*scratch* buffer to bootstrap
quelpa. Add it to your Emacs init file to make sure
quelpa will be installed and upgraded automatically when needed.
If you don't like
quelpa doing self-upgrades (although this is recommended), use the following snippet instead:
(package-initialize) (unless (require 'quelpa nil t) (with-temp-buffer (url-insert-file-contents "https://framagit.org/steckerhalter/quelpa/raw/master/bootstrap.el") (eval-buffer)))
(package-initialize) can be omitted if you are already running the command before the snippet in your init file.
Cool. Now that we are all setup, enjoy the ride.
There are two ways to install packages with
Installing with a package name
Check https://melpa.org/ for any packages you would like to install. You only need to know the name:
Running this expression will fetch the
magit source code from Github, build a package in the ELPA format and install it.
Interactive installation is supported as well. Just execute
M-x quelpa and select a recipe name from MELPA.
If the package has dependencies they will be installed first.
Installing with a recipe
You can also install packages that are not on MELPA. For this you need to provide a recipe in MELPA's format.
The recipe is a list and consist of the package name and keywords. A minimal recipe would look like this:
'(discover-my-major :fetcher git :url "https://framagit.org/steckerhalter/discover-my-major.git")
Depending on the fetcher, different keywords can or have to be supplied. So to install
discover-my-major you would have to use:
(quelpa '(discover-my-major :fetcher git :url "https://framagit.org/steckerhalter/discover-my-major.git"))
Don't forget the quote before the recipe.
Upgrading individual packages
quelpa does not do anything if a package is already installed. You can customize this behavior globally by setting the variable
(setq quelpa-upgrade-p t)
Alternatively customize this variable by executing
M-x customize-variable quelpa-upgrade-p RET.
It is also possible to override this default behavior for individual packages:
quelpa is called interactively with a prefix argument (e.g
C-u M-x quelpa) it will try to upgrade the given package even if the global variable
quelpa-upgrade-p is set to nil.
C-u M-x quelpa magit RET will upgrade magit.
Please note that the
:upgrade parameter described below is still preferred over the prefix argument.
(quelpa 'company :upgrade t)
quelpa will try to upgrade
company even if upgrading is disabled globally.
(quelpa '(ag :repo "Wilfred/ag.el" :fetcher github) :upgrade nil)
When used that way,
quelpa will not upgrade
ag. This can be used to "pin" packages when evaluating a buffer with
Upgrading all packages
Upgrading all your
quelpa packages at init is one option to keep them up to date, but can slow it down considerably. Alternatively you can execute
M-x quelpa-upgrade and upgrade every cached package.
This command relies on an intact cache file which is set in the
quelpa-cache-file variable. It is updated after every
quelpa invocation. To reset it for debugging purposes, just delete the file and better keep a backup.
quelpa also upgrades itself as well here. You can disable this by setting
(setq quelpa-self-upgrade-p nil)
quelpa can be instructed to build stable packages. This means that the repository with the source code (
hg are supported) is queried for a stable tag and if one is found that version will be built.
For more information please see MELPA's notes on stable packages.
quelpa there is a global variable where building of stable packages can be enabled, so that all packages are built stable (if available for the individual package):
(setq quelpa-stable-p t)
or you can set it just for one package by supplying
stable as an argument:
(quelpa 'anzu :stable t)
or as part of the recipe itself:
(quelpa '(ag :repo "Wilfred/ag.el" :fetcher github :stable t))
The definition as part of the recipe has the highest priority and overrides the other two methods. Likewise adding it as an argument overrides the global variable. So the priority is like: recipe > argument >
Note that dev version numbers are usually higher than stable version numbers (they are using the build date as version) so if you want to install a stable version for an installed dev package you will first have to uninstall that package.
quelpa installs packages using the built-in Emacs package management system, you can use its regular interface by executing
M-x list-packages and work with your packages as you would normally do. Deleting a package does not affect the
quelpa cache yet.
quelpa does not remove obsolete packages after upgrades. To delete all obsolete packages from time to time use:
M-x list-packages RET
~to mark all obsolete packages for deletion
xand confirm deletion
Builds packages from single
.el files. It works like this:
(quelpa '(rainbow-mode :url "http://git.savannah.gnu.org/cgit/emacs/elpa.git/plain/packages/rainbow-mode/rainbow-mode.el" :fetcher url))
You specify the
:url (either a remote or local one like
file:///path/to/file.el) of the file and as
(quelpa '(ox-rss :url "http://orgmode.org/cgit.cgi/org-mode.git/plain/contrib/lisp/ox-rss.el" :fetcher url))
By default upgrades are managed through file hashes, so if the content changed,
quelpa will upgrade the package. Existing version numbers are retained.
quelpa uses a version suffix that still allows the original version to have priority. So if you should install a package from another source with the same version it will be preferred.
To keep the original version unmodified use the parameter
:version original. For example:
(quelpa '(queue :url "http://www.dr-qubit.org/download.php?file=predictive/queue.el" :fetcher url :version original))
Builds single-file packages from local
(quelpa '(rainbow-mode :fetcher file :path "/path/to/rainbow-mode/rainbow-mode.el"))
Or multi-file packages from a local directory:
;; You can also use `~' in the :path and it will expand to the home directory. (quelpa '(rainbow-mode :fetcher file :path "~/path/to/rainbow-mode/dir"))
Specifying a directory for the
:path does not retain existing version numbers,
nor does it make any use of the
:version original parameter.
Inhibit MELPA git checkout or updates on init
quelpa usually updates the MELPA git repo (stored in
package-build) which ensures you always have the latest recipes from MELPA available. This causes as small delay and some people don't like that (presumably people that do not use or know
emacs --daemon and
You can disable these updates by setting
nil before requiring
(setq quelpa-update-melpa-p nil)
Or, if you don't want to use the MELPA git repo at all (e.g. if you're using
quelpa mainly for installing packages outside of MELPA,) you can also set
(setq quelpa-checkout-melpa-p nil)
Modify MELPA Recipes
When installing a package,
quelpa will install any listed dependencies via the recipe that MELPA has for it. But maybe you want to use a different recipe, or perhaps the dependency is not even on MELPA, which would cause an installation failure.
You can create a directory with recipe files and tell
quelpa to look there for an appropriate recipe:
(add-to-list 'quelpa-melpa-recipe-stores "/path/to/custom/recipe/dir")
This way, if no recipe is found in this custom directory, it will fallback to the next directory in the list, which in this case would be the directory containing the recipes from MELPA.
The files themselves should be named after the package name, without any extension like
Alternatively, you can also specify a list of recipes instead.
As MacOS is a BSD-based operating system, its
tar command is different from GNU Tar. If you're using an additional package manager, it should be possible to install GNU tar to resolve the issue.
People using homebrew will be able to install the package using the homebrew package of
People using MacPorts or Ports, which is similar in maby ways to the pkg system on FreeBSD, can resolve the issue by installing the
On Windows there are some caveats so the procedure to make Emacs work with
quelpa is outlined below. You can either use the native Windows build from GNU or the Cygwin port. If you'd like to have a complete *nix environment on your Windows machine then the Cygwin version is to be preferred.
The Cygwin port is also easier to install as there are less manual steps necessary.
Download either the 64-bit or 32-bit setup file from http://cygwin.com/install.html. If your Windows version is 64-bit then make sure to use the 64-bit installer to avoid some problems that only happen with the 32-bit version.
It is usually better to install Cygwin just for the current user, not system-wide:
- Open the location where you have downloaded the setup executable in Explorer
- Press shift and right-click -> open command prompt here
Run for example:
Just leave the default packages selected and finish the installer
Install a sane package manager
Install apt-cyg from https://github.com/transcode-open/apt-cyg:
Open the Cygwin terminal and execute:
lynx -source rawgit.com/transcode-open/apt-cyg/master/apt-cyg > apt-cyg install apt-cyg /bin
Then install Emacs like this:
apt-cyg install wget git emacs-w32 emacs-el
This will take quite a while...
Fix issue on 32-bit Cygwin
Using the 32-bit version of Cygwin I've got weird vfork errors and had to do a rebase (see http://cygwin.wikia.com/wiki/Rebaseall):
- Close the Cygwin terminal
- Start/Run: "C:\cygwin\bin\dash.exe" (adapt the path to your Cygwin install)
- Close dash
So then everything should work with
quelpa. Open the Cygwin terminal, install your init file and enjoy Emacs on Windows (even
emacs --daemon works with the Cygwin build)
Download and unpack Emacs from https://ftp.gnu.org/gnu/emacs/windows/ (for example to
Some libraries are missing for SSL to work with Emacs so you will have to download the gnutls build from sourceforge: http://sourceforge.net/projects/ezwinports/files/
Copy all .dll files from the gnutls archive to the
c:\emacs\bin to the Windows
PATH environment variable.
Install Git from https://git-scm.com/download/win. Make sure to choose these options in the installer:
Use Git from the Windows Command Prompt
tar is needed by
quelpa to build the
elpa packages and has to be installed additionally.
Download MinGW from http://sourceforge.net/projects/mingw/files/latest/download and start the installer.
When you can choose the packages that should get installed go to
All Packages ->
MSYS Base System and mark
msys-tar (bin) for installation. Then apply the changes.
Then Emacs should work with
The german word
spring (as in: water source) but also
source code is translated to
ELPA is the abbreviation for Emacs Lisp Package Archive. You get the idea.