MELPA

MELPA is a growing collection of package.el-compatible Emacs Lisp packages built automatically on our server from the upstream source code using simple recipes. (Think of it as a server-side version of [el-get], or even [Homebrew].)

Packages are updated at intervals throughout the day.

To browse available packages, check out the [archive index page][MELPA].

Adding packages is as simple as submitting a new recipe as a pull request; read on for details.

Usage
Contributing
Recipe Format
Build Scripts
API
Configuration
Mirrors
About

Usage

To use the MELPA repository, you'll need an Emacs with package.el, i.e., Emacs 24.1 or greater. To test TLS support you can visit a HTTPS URL, for example with M-x eww RET https://wikipedia.org RET.

Enable installation of packages from MELPA by adding an entry to package-archives after (require 'package) and before the call to package-initialize in your init.el or .emacs file:

(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
;; Comment/uncomment this line to enable MELPA Stable if desired.
;; See `package-archive-priorities` and `package-pinned-packages`.
;; Most users will not need or want to do this.
;; (add-to-list 'package-archives
;;              '("melpa-stable" . "https://stable.melpa.org/packages/") t)
(package-initialize)

Then just use M-x package-list-packages to browse and install packages from MELPA and elsewhere.

Note that you'll need to run M-x package-refresh-contents or M-x package-list-packages to ensure that Emacs has fetched the MELPA package list before you can install packages with M-x package-install or similar.

MELPA Stable

Packages in MELPA are built directly from the latest package source code in the upstream repositories, but we also build and publish packages corresponding to the latest tagged code in those repositories, where version tags exist. These packages are published in a separate package archive called [MELPA Stable]. Most users should prefer MELPA over MELPA Stable.

Some notes:

If you leave the original MELPA server in your package-archives then by default you will get the development versions of packages and not the stable ones, because the development versions are higher.
If your Emacs has the variables package-pinned-packages (available in 24.4 and later) and/or package-archive-priorities, you can customize or modify those variables as needed.
You can use the [package-filter] package which we provide.
You will probably want to remove all packages and then reinstall them. Any packages you already have installed from MELPA will never get "updated" to the stable version because of the way version numbering is handled.

Note that the MELPA maintainers do not use MELPA Stable themselves, and do not particularly recommend its use.

Contributing

See the [CONTRIBUTING.org] document.

Recipe Format

Packages are specified by files in the recipes directory. You can contribute a new package by adding a new file under recipes using the following form ([...] denotes optional or conditional values),

(<package-name>
 :fetcher [git|github|gitlab|codeberg|sourcehut|hg]
 [:url "<repo url>"]
 [:repo "user-name/repo-name"]
 [:commit "commit"]
 [:branch "branch"]
 [:version-regexp "<regexp>"]
 [:files ("<file1>" ...)]
 [:old-names (<old-name> ...)])

package-name a lisp symbol that has the same name as the package being specified.
:fetcher specifies the type of repository the package is being maintained in.

Melpa supports the Git and Mercurial version control systems and provides generic fetcher types for them: git and hg. When you use one of these fetchers, you must specify the :url property.

Melpa also provides dedicated fetchers for certain Git forges (aka "Git repository hosting platforms"), which should always be preferred over the generic git fetcher. When using a dedicated fetcher, you must specify :repo, not :url. Currently these Git forge fetchers exist: [github], [gitlab], [codeberg] and [sourcehut].

There are no dedicated fetchers for Mercurial. When a forge supports both Git and Mercurial, then the respective fetcher can only be used for Git repositories. For Mercurial repositories always use the hg fetcher.
:url specifies the URL of the version control repository. It is required for the generic git and hg fetchers and is invalid for forge-specific fetchers.
:repo specifies the repository used by forge-specific fetchers and is of the form user-name/repo-name. It is required for forge-specific fetchers and is invalid for the generic fetchers.

Note that user names in Sourcehut URLs are prefixed with ~, that has to be omitted in the value of this property.
:commit specifies the commit of the Git repository to checkout. The value will be passed to git reset in a repo where upstream is the original repository. Can therefore be either a SHA, if pointing at a specific commit, or a full ref prefixed with "origin/". Only used by the git-based fetchers.
:branch specifies the branch of the Git repository to use. This is like :commit, but it adds the "origin/" prefix automatically. This must be specified when using a branch other than the default branch.
:version-regexp is a regular expression for extracting a version-string from the repository tags. The default matches typical version tags such as 1.0, R16 or v4.3.5, so you should not override it unless necessary. For an unusual tag like "OTP-18.1.5", we might add :version-regexp "[^0-9]*\\(.*\\)" to strip the "OTP-" prefix. The captured portion of the regexp must be parseable by Emacs' version-to-list function.
:files optional property specifying the Emacs Lisp libraries and info files used to build the package. Please do not override this if the default value (below) is adequate, which it should usually be:
```
'("*.el" "lisp/*.el"
  "dir" "*.info" "*.texi" "*.texinfo"
  "doc/dir" "doc/*.info" "doc/*.texi" "doc/*.texinfo"
  "docs/dir" "docs/*.info" "docs/*.texi" "docs/*.texinfo"
  (:exclude
   ".*.el" "lisp/.*.el"
   "test.el" "tests.el" "*-test.el" "*-tests.el"
   "lisp/test.el" "lisp/tests.el" "lisp/*-test.el" "lisp/*-tests.el"))
```
Note that you should place Emacs Lisp libraries in the root of the repository or in the lisp/ directory. Test files should be placed in the test/ directory and they should not provide a feature. Note that all Emacs Lisp files whose name begin with a period are excluded.

No NAME-pkg.el should be checked into version control. This file is generated from metadata found in the "main library" (NAME.el). This is true not only for MELPA, but also GNU ELPA and NonGNU ELPA.

Please do not track any third-party libraries and test utilities in your repository. If you absolutely must do it, then place these files in a directory dedicated to that purpose, alongside a file named .nosearch. The latter prevents various tools from adding the containing directory to the load-path or from otherwise getting confused.

The elements of the :files list are glob-expanded to make a list of paths that will be copied into the root of the new package. This means a file like lisp/foo.el would become foo.el in the new package. To specify a destination subdirectory, use a list element of the form (TARGET-DIR SOURCE-PATH ...).

To exclude certain paths, use (:exclude SOURCE-PATH ...). There should only be one element that begins with :exclude and it should be the last element, though that is not enforced at this time.

If your package requires some additional files, but is otherwise fine with the defaults, use the special element :defaults as the first element of the :files list. This causes the default value shown above to be prepended to the specified file list. For example :files (:defaults "snippets") would cause the snippets subdir to be copied in addition to the defaults.

Warning: Elements of :files are (no longer) processed in order because we feed these globs to git log or hg log to determine the last commit that touched a relevant file. These commands unfortunately process all exclude globs after all include globs. Therefore it is not possible to override the :exclude element that appears in :defaults in a later element of :files. This means that a package whose name ends with -test cannot use :defaults. Likewise if the name of a library (as opposed to a file implementing tests) ends with -test.el, then :defaults cannot be used.

Warning: Once the appropriate commit has been determined file-expand-wildcards is used to determine the files matched by each glob. Unfortunately (unlike in a shell) a glob that begins with * may also match filenames that begin with ., so you might have to add exclude globs to prevent those from being included. :defaults takes care to exclude .dir-locals.el; if you don't use :defaults, then you might have to exclude that explicitly.
:old-names specifies former names of the package, if any. The value is a list of symbols.

Example: Single File Repository

smex is a repository that contains two files:

README.markdown
smex.el

Since there is only one .el file, this package only needs the :fetcher and :repo specified,

(smex :fetcher github :repo "nonsequitur/smex")

Example: Multiple Packages in one Repository

Assume we

Melpa

Install / Use

README