1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software
4 @c See file emacs.texi for copying conditions.
6 @chapter Emacs Lisp Packages
8 @cindex Emacs Lisp package archive
9 @cindex Package archive
10 @cindex Emacs Lisp package
12 Emacs includes a facility that lets you easily download and install
13 @dfn{packages} that implement additional features. Each package is a
14 separate Emacs Lisp program, sometimes including other components such
17 @kbd{M-x list-packages} brings up a buffer named @file{*Packages*}
18 with a list of all packages. You can install or uninstall packages
19 via this buffer. @xref{Package Menu}.
21 @findex describe-package
22 The command @kbd{C-h P} (@code{describe-package}) prompts for the
23 name of a package, and displays a help buffer describing the
24 attributes of the package and the features that it implements.
26 By default, Emacs downloads packages from a @dfn{package archive}
27 maintained by the Emacs developers and hosted by the GNU project.
28 Optionally, you can also download packages from archives maintained by
29 third parties. @xref{Package Installation}.
31 For information about turning an Emacs Lisp program into an
32 installable package, @xref{Packaging,,,elisp, The Emacs Lisp Reference
33 Manual}. For information about finding third-party packages and other
34 Emacs Lisp extensions, @xref{Packages that do not come with
35 Emacs,,,efaq, GNU Emacs FAQ}.
38 * Package Menu:: Buffer for viewing and managing packages.
39 * Package Installation:: Options for package installation.
40 * Package Files:: Where packages are installed.
44 @section The Package Menu Buffer
46 @cindex built-in package
49 The command @kbd{M-x list-packages} brings up the @dfn{package menu}.
50 This is a buffer listing all the packages that Emacs knows about, one
51 on each line, with the following information:
55 The package name (e.g., @samp{auctex}).
58 The package's version number (e.g., @samp{11.86}).
61 The package's status---normally one of @samp{available} (can be
62 downloaded from the package archive), @samp{installed},
63 @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
64 or @samp{built-in} (included in Emacs by default).
66 The status can also be @samp{new}. This is equivalent to
67 @samp{available}, except that it means the package became newly
68 available on the package archive after your last invocation of
69 @kbd{M-x list-packages}. In other instances, a package may have the
70 status @samp{held}, @samp{disabled}, or @samp{obsolete}.
71 @xref{Package Installation}.
74 A short description of the package.
78 The @code{list-packages} command accesses the network, to retrieve the
79 list of available packages from the package archive server. If the
80 network is unavailable, it falls back on the most recently retrieved
83 The following commands are available in the package menu:
87 Print a short message summarizing how to use the package menu
88 (@code{package-menu-quick-help}).
92 Display a help buffer for the package on the current line
93 (@code{package-menu-describe-package}), similar to the help window
94 displayed by the @kbd{C-h P} command (@pxref{Packages}).
97 Mark the package on the current line for installation
98 (@code{package-menu-mark-install}). If the package status is
99 @samp{available}, this adds an @samp{I} character to the start of the
100 line; typing @kbd{x} (see below) will download and install the
104 Mark the package on the current line for deletion
105 (@code{package-menu-mark-delete}). If the package status is
106 @samp{installed}, this adds a @samp{D} character to the start of the
107 line; typing @kbd{x} (see below) will delete the package.
108 @xref{Package Files}, for information about what package deletion
112 Remove any installation or deletion mark previously added to the
113 current line by an @kbd{i} or @kbd{d} command.
116 Mark all package with a newer available version for ``upgrading''
117 (@code{package-menu-mark-upgrades}). This places an installation mark
118 on the new available versions, and a deletion mark on the old
122 Download and install all packages marked with @kbd{i}, and their
123 dependencies; also, delete all packages marked with @kbd{d}
124 (@code{package-menu-execute}). This also removes the marks.
127 Refresh the package list (@code{package-menu-refresh}). This fetches
128 the list of available packages from the package archive again, and
129 recomputes the package list.
132 Filter the package list (@code{package-menu-filter}). This prompts
133 for a keyword (e.g., @samp{games}), then shows only the packages
134 that relate to that keyword. To restore the full package list,
139 For example, you can install a package by typing @kbd{i} on the line
140 listing that package, followed by @kbd{x}.
142 @node Package Installation
143 @section Package Installation
145 @findex package-install
146 Packages are most conveniently installed using the package menu
147 (@pxref{Package Menu}), but you can also use the command @kbd{M-x
148 package-install}. This prompts for the name of a package with the
149 @samp{available} status, then downloads and installs it.
151 @cindex package requirements
152 A package may @dfn{require} certain other packages to be installed,
153 because it relies on functionality provided by them. When Emacs
154 installs such a package, it also automatically downloads and installs
155 any required package that is not already installed. (If a required
156 package is somehow unavailable, Emacs signals an error and stops
157 installation.) A package's requirements list is shown in its help
160 @vindex package-archives
161 By default, packages are downloaded from a single package archive
162 maintained by the Emacs developers. This is controlled by the
163 variable @code{package-archives}, whose value is a list of package
164 archives known to Emacs. Each list element must have the form
165 @code{(@var{id} . @var{location})}, where @var{id} is the name of a
166 package archive and @var{location} is the @acronym{HTTP} address or
167 directory name of the package archive. You can alter this list if you
168 wish to use third party package archives---but do so at your own risk,
169 and use only third parties that you think you can trust!
171 @anchor{Package Signing}
172 @cindex package security
173 @cindex package signing
174 The maintainers of package archives can increase the trust that you
175 can have in their packages by @dfn{signing} them. They generate a
176 private/public pair of cryptographic keys, and use the private key to
177 create a @dfn{signature file} for each package. With the public key, you
178 can use the signature files to verify who created the package, and
179 that it has not been modified. A valid signature is not a cast-iron
180 guarantee that a package is not malicious, so you should still
181 exercise caution. Package archives should provide instructions
182 on how you can obtain their public key. One way is to download the
183 key from a server such as @url{http://pgp.mit.edu/}.
184 Use @kbd{M-x package-import-keyring} to import the key into Emacs.
185 Emacs stores package keys in the @file{gnupg} subdirectory
186 of @code{package-user-dir}.
187 The public key for the GNU package archive is distributed with Emacs,
188 in the @file{etc/package-keyring.gpg}. Emacs uses it automatically.
190 @vindex package-check-signature
191 @vindex package-unsigned-archives
192 If the user option @code{package-check-signature} is non-@code{nil},
193 Emacs attempts to verify signatures when you install packages. If the
194 option has the value @code{allow-unsigned}, you can still install a
195 package that is not signed. If you use some archives that do not sign
196 their packages, you can add them to the list @code{package-unsigned-archives}.
198 For more information on cryptographic keys and signing,
199 @pxref{Top,, Top, gnupg, The GNU Privacy Guard Manual}.
200 Emacs comes with an interface to GNU Privacy Guard,
201 @pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}.
203 @vindex package-pinned-packages
204 If you have more than one package archive enabled, and some of them
205 offer different versions of the same package, you may find the option
206 @code{package-pinned-packages} useful. You can add package/archive
207 pairs to this list, to ensure that the specified package is only ever
208 downloaded from the specified archive.
210 Once a package is downloaded and installed, it is @dfn{loaded} into
211 the current Emacs session. Loading a package is not quite the same as
212 loading a Lisp library (@pxref{Lisp Libraries}); its effect varies
213 from package to package. Most packages just make some new commands
214 available, while others have more wide-ranging effects on the Emacs
215 session. For such information, consult the package's help buffer.
217 By default, Emacs also automatically loads all installed packages in
218 subsequent Emacs sessions. This happens at startup, after processing
219 the init file (@pxref{Init File}). As an exception, Emacs does not
220 load packages at startup if invoked with the @samp{-q} or
221 @samp{--no-init-file} options (@pxref{Initial Options}).
223 @vindex package-enable-at-startup
224 To disable automatic package loading, change the variable
225 @code{package-enable-at-startup} to @code{nil}.
227 @findex package-initialize
228 The reason automatic package loading occurs after loading the init
229 file is that user options only receive their customized values after
230 loading the init file, including user options which affect the
231 packaging system. In some circumstances, you may want to load
232 packages explicitly in your init file (usually because some other code
233 in your init file depends on a package). In that case, your init file
234 should call the function @code{package-initialize}. It is up to you
235 to ensure that relevant user options, such as @code{package-load-list}
236 (see below), are set up prior to the @code{package-initialize} call.
237 You should also set @code{package-enable-at-startup} to @code{nil}, to
238 avoid loading the packages again after processing the init file.
239 Alternatively, you may choose to completely inhibit package loading at
240 startup, and invoke the command @kbd{M-x package-initialize} to load
241 your packages manually.
243 @vindex package-load-list
244 For finer control over package loading, you can use the variable
245 @code{package-load-list}. Its value should be a list. A list element
246 of the form @code{(@var{name} @var{version})} tells Emacs to load
247 version @var{version} of the package named @var{name}. Here,
248 @var{version} should be a version string (corresponding to a specific
249 version of the package), or @code{t} (which means to load any
250 installed version), or @code{nil} (which means no version; this
251 ``disables'' the package, preventing it from being loaded). A list
252 element can also be the symbol @code{all}, which means to load the
253 latest installed version of any package not named by the other list
254 elements. The default value is just @code{'(all)}.
256 For example, if you set @code{package-load-list} to @code{'((muse
257 "3.20") all)}, then Emacs only loads version 3.20 of the @samp{muse}
258 package, plus any installed version of packages other than
259 @samp{muse}. Any other version of @samp{muse} that happens to be
260 installed will be ignored. The @samp{muse} package will be listed in
261 the package menu with the @samp{held} status.
264 @section Package Files and Directory Layout
265 @cindex package directory
268 @findex package-install-file
269 Each package is downloaded from the package archive in the form of a
270 single @dfn{package file}---either an Emacs Lisp source file, or a tar
271 file containing multiple Emacs Lisp source and other files. Package
272 files are automatically retrieved, processed, and disposed of by the
273 Emacs commands that install packages. Normally, you will not need to
274 deal directly with them, unless you are making a package
275 (@pxref{Packaging,,,elisp, The Emacs Lisp Reference Manual}). Should
276 you ever need to install a package directly from a package file, use
277 the command @kbd{M-x package-install-file}.
279 @vindex package-user-dir
280 Once installed, the contents of a package are placed in a
281 subdirectory of @file{~/.emacs.d/elpa/} (you can change the name of
282 that directory by changing the variable @code{package-user-dir}). The
283 package subdirectory is named @file{@var{name}-@var{version}}, where
284 @var{name} is the package name and @var{version} is its version
287 @cindex system-wide packages
288 @vindex package-directory-list
289 In addition to @code{package-user-dir}, Emacs looks for installed
290 packages in the directories listed in @code{package-directory-list}.
291 These directories are meant for system administrators to make Emacs
292 packages available system-wide; Emacs itself never installs packages
293 there. The package subdirectories for @code{package-directory-list}
294 are laid out in the same way as in @code{package-user-dir}.
296 Deleting a package (@pxref{Package Menu}) involves deleting the
297 corresponding package subdirectory. This only works for packages
298 installed in @code{package-user-dir}; if told to act on a package in a
299 system-wide package directory, the deletion command signals an error.