@c This is part of the Emacs manual.
@c Copyright (C) 1985--1987, 1993--1995, 1997, 2000--2025 Free Software
@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Packages
@chapter Emacs Lisp Packages
@cindex Package
@cindex Package archive

  Emacs is extended by implementing additional features in
@dfn{packages}, which are Emacs Lisp libraries.  These could be
written by you or provided by someone else.  If you want to install
such a package so it is available in your future Emacs session, you
need to compile it and put it in a directory where Emacs looks for
Lisp libraries.  @xref{Lisp Libraries}, for more details about this
manual installation method.  Many packages provide installation and
usage instructions in the large commentary near the beginning of the
Lisp file; you can use those instructions for installing and
fine-tuning your use of the package.

@cindex Emacs Lisp package archive
  Packages can also be provided by @dfn{package archives}, which are
large collections of Emacs Lisp packages.  Each package is a separate
Emacs Lisp program, sometimes including other components such as an
Info manual.  Emacs includes a facility that lets you easily download
and install packages from such archives.  The rest of this chapter
describes this facility.

  To list the packages available for installation from package
archives, type @w{@kbd{M-x list-packages @key{RET}}}.  It brings up a
buffer named @file{*Packages*} with a list of all packages.  You can
install or uninstall packages via this buffer.  @xref{Package Menu}.

  The command @kbd{C-h P} (@code{describe-package}) prompts for the
name of a package, and displays a help buffer describing the
attributes of the package and the features that it implements.

  By default, Emacs downloads packages from two archives:
@url{https://elpa.gnu.org/, GNU ELPA} and @url{https://elpa.nongnu.org/,
NonGNU ELPA}.  These are maintained by the Emacs developers and hosted
by the GNU project.  Optionally, you can also download packages from
third-party archives.  @xref{Package Installation}.

  For information about turning an Emacs Lisp program into an
installable package, @xref{Packaging,,,elisp, The Emacs Lisp Reference
Manual}.

@menu
* Package Menu::         Buffer for viewing and managing packages.
* Package Statuses::     Which statuses a package can have.
* Package Installation:: Options for package installation.
* Package Files::        Where packages are installed.
* Fetching Package Sources::  Managing packages directly from source.
@end menu

@node Package Menu
@section The Package Menu Buffer
@cindex package menu
@cindex built-in package
@findex list-packages

The command @kbd{M-x list-packages} brings up the @dfn{package menu}.
This is a buffer listing all the packages that Emacs knows about, one
on each line, with the following information:

@itemize @bullet
@item
The package name (e.g., @samp{auctex}).

@item
The package's version number (e.g., @samp{11.86}).

@item
The package's status---normally one of @samp{available} (can be
downloaded from the package archive), @samp{installed},
@c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
or @samp{built-in} (included in Emacs by default).
@xref{Package Statuses}.

@item
Which package archive this package is from, if you have more than one
package archive enabled.

@item
A short description of the package.
@end itemize

@noindent
The @code{list-packages} command accesses the network, to retrieve the
list of available packages from package archive servers.  If the
network is unavailable, it falls back on the most recently retrieved
list.

The main command to use in the package list buffer is the @key{x}
command.  If the package under point isn't installed already, this
command will install it.  If the package under point is already
installed, this command will delete it.

The following commands are available in the package menu:

@table @kbd
@item h
@kindex h @r{(Package Menu)}
@findex package-menu-quick-help
Print a short message summarizing how to use the package menu
(@code{package-menu-quick-help}).

@item ?
@itemx @key{RET}
@kindex ? @r{(Package Menu)}
@kindex RET @r{(Package Menu)}
@findex package-menu-describe-package
Display a help buffer for the package on the current line
(@code{package-menu-describe-package}), similar to the help window
displayed by the @kbd{C-h P} command (@pxref{Packages}).

@item i
@kindex i @r{(Package Menu)}
@findex package-menu-mark-install
Mark the package on the current line for installation
(@code{package-menu-mark-install}).  If the package status is
@samp{available}, this adds an @samp{I} character to the start of the
line; typing @kbd{x} (see below) will download and install the
package.

@item d
@kindex d @r{(Package Menu)}
@findex package-menu-mark-delete
Mark the package on the current line for deletion
(@code{package-menu-mark-delete}).  If the package status is
@samp{installed}, this adds a @samp{D} character to the start of the
line; typing @kbd{x} (see below) will delete the package.
@xref{Package Files}, for information about what package deletion
entails.

@item w
@kindex w @r{(Package Menu)}
@findex package-browse-url
Open the package website on the current line in a browser
(@code{package-browse-url}).  @code{browse-url} is used to open the
browser.

@item ~
@kindex ~ @r{(Package Menu)}
@findex package-menu-mark-obsolete-for-deletion
Mark all obsolete packages for deletion
(@code{package-menu-mark-obsolete-for-deletion}).  This marks for
deletion all the packages whose status is @samp{obsolete}.

@item u
@itemx @key{DEL}
@kindex u @r{(Package Menu)}
@findex package-menu-mark-unmark
Remove any installation or deletion mark previously added to the
current line by an @kbd{i} or @kbd{d} command
(@code{package-menu-mark-unmark}).

@item U
@kindex U @r{(Package Menu)}
@findex package-menu-mark-upgrades
Mark all package with a newer available version for upgrading
(@code{package-menu-mark-upgrades}).  This places an installation mark
on the new available versions, and a deletion mark on the old
installed versions (marked with status @samp{obsolete}).  By default,
this won't mark built-in packages for which a newer version is
available, but customizing @code{package-install-upgrade-built-in} can
change that.  @xref{Package Installation}.  If you customize
@code{package-install-upgrade-built-in} to a non-@code{nil} value, be
sure to review all the built-in packages the @kbd{U} command marks, to
avoid updating built-in packages you don't want to overwrite.

@item x
@kindex x @r{(Package Menu)}
@vindex package-menu-async
@findex package-menu-execute
Download and install all packages marked with @kbd{i}, and their
dependencies; also, delete all packages marked with @kbd{d}
(@code{package-menu-execute}).  This also removes the marks.  If no
packages are marked, this command will install the package under point
(if it isn't installed already), or delete the package under point (if
it's already installed).

@item g
@item r
@kindex g @r{(Package Menu)}
@kindex r @r{(Package Menu)}
Refresh the package list (@code{revert-buffer}).  This fetches the
list of available packages from the package archive again, and
redisplays the package list.

@item H
@kindex H @r{(Package Menu)}
@findex package-menu-hide-package
Hide packages whose names match a regexp
(@code{package-menu-hide-package}).  This prompts for a regexp, and
then hides the packages with matching names.  The default value of the
regexp will hide only the package whose name is at point, so just
pressing @key{RET} to the prompt will hide the current package.

@item (
@kindex ( @r{(Package Menu)}
@findex package-menu-toggle-hiding
Toggle visibility of old versions of packages and also of versions
from lower-priority archives (@code{package-menu-toggle-hiding}).

@item / a
@kindex / a @r{(Package Menu)}
@findex package-menu-filter-by-archive
Filter package list by archive (@code{package-menu-filter-by-archive}).
This prompts for a package archive (e.g., @samp{gnu}), then shows only
packages from that archive.  You can specify several archives by
typing their names separated by commas.

@item / d
@kindex / d @r{(Package Menu)}
@findex package-menu-filter-by-description
Filter package list by description
(@code{package-menu-filter-by-description}).  This prompts for a
regular expression, then shows only packages with descriptions
matching that regexp.

@item / k
@kindex / k @r{(Package Menu)}
@findex package-menu-filter-by-keyword
Filter package list by keyword (@code{package-menu-filter-by-keyword}).
This prompts for a keyword (e.g., @samp{games}), then shows only
packages with that keyword.  You can specify several keywords by
typing them separated by commas.

@item / N
@kindex / N @r{(Package Menu)}
@findex package-menu-filter-by-name-or-description
Filter package list by name or description
(@code{package-menu-filter-by-name-or-description}).  This prompts for
a regular expression, then shows only packages with a name or
description matching that regexp.

@item / n
@kindex / n @r{(Package Menu)}
@findex package-menu-filter-by-name
Filter package list by name (@code{package-menu-filter-by-name}).
This prompts for a regular expression, then shows only packages
with names matching that regexp.

@item / s
@kindex / s @r{(Package Menu)}
@findex package-menu-filter-by-status
Filter package list by status (@code{package-menu-filter-by-status}).
This prompts for one or more statuses (e.g., @samp{available},
@pxref{Package Statuses}), then shows only packages with matching
status.  You can specify several status values by typing them
separated by commas.

@item / v
@kindex / v @r{(Package Menu)}
@findex package-menu-filter-by-version
Filter package list by version (@code{package-menu-filter-by-version}).
This prompts first for one of the comparison symbols @samp{<},
@samp{>} or @samp{=} and for a version string, and then shows packages
whose versions are correspondingly lower, equal or higher than the
version you typed.

@item / m
@kindex / m @r{(Package Menu)}
@findex package-menu-filter-marked
Filter package list by non-empty mark (@code{package-menu-filter-marked}).
This shows only the packages that have been marked to be installed or deleted.

@item / u
@kindex / u @r{(Package Menu)}
@findex package-menu-filter-upgradable
Filter package list to show only packages for which there are
available upgrades (@code{package-menu-filter-upgradable}).  By
default, this filter excludes the built-in packages for which a newer
version is available, but customizing
@code{package-install-upgrade-built-in} can change that.
@xref{Package Installation}.

@item / /
@kindex / / @r{(Package Menu)}
@findex package-menu-filter-clear
Clear filter currently applied to the package list
(@code{package-menu-filter-clear}).
@end table

@noindent
For example, you can install a package by typing @kbd{i} on the line
listing that package, followed by @kbd{x}.

@node Package Statuses
@section Package Statuses
@cindex package status

A package can have one of the following statuses:

@table @samp
@item available
The package is not installed, but can be downloaded and installed from
the package archive.

@item avail-obso
The package is available for installation, but a newer version is also
available.  Packages with this status are hidden by default.

@cindex built-in package
@item built-in
The package is included in Emacs by default.  It cannot be deleted
through the package menu, and by default is not considered for
upgrading (but you can change that by customizing
@code{package-install-upgrade-built-in}, @pxref{Package Installation}).

@item dependency
The package was installed automatically to satisfy a dependency of
another package.

@item disabled
The package has been disabled using the @code{package-load-list}
variable.

@item external
The package is not built-in and not from the directory specified by
@code{package-user-dir} (@pxref{Package Files}).  External packages
are treated much like @samp{built-in} packages and cannot be deleted.

@item held
The package is held, @xref{Package Installation}.

@item incompat
The package cannot be installed for some reason, for example because
it depends on uninstallable packages.

@item installed
The package is installed.

@item new
Equivalent to @samp{available}, except that the package became newly
available on the package archive after your last invocation of
@kbd{M-x list-packages}.

@item obsolete
The package is an outdated installed version; in addition to this
version of the package, a newer version is also installed.

@c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
@end table

@node Package Installation
@section Package Installation

@findex package-install
@findex package-upgrade
@findex package-upgrade-all
  Packages are most conveniently installed using the package menu
(@pxref{Package Menu}), but you can also use the command @kbd{M-x
package-install}.  This prompts for the name of a package with the
@samp{available} status, then downloads and installs it.  Similarly,
if you want to upgrade a package, you can use the @kbd{M-x
package-upgrade} command, and if you want to upgrade all the packages,
you can use the @kbd{M-x package-upgrade-all} command.

@vindex package-install-upgrade-built-in
  By default, @code{package-install} doesn't consider built-in
packages for which new versions are available from the archives.  (A
package is built-in if it is included in the Emacs distribution.)  In
particular, it will not show built-in packages in the list of
completion candidates when you type at its prompt.  But if you invoke
@code{package-install} with a prefix argument, it will also consider
built-in packages that can be upgraded.  You can make this behavior
the default by customizing the variable
@code{package-install-upgrade-built-in}: if its value is
non-@code{nil}, @code{package-install} will consider built-in packages
even when invoked without a prefix argument.  Note that the
package-menu commands (@pxref{Package Menu}) are also affected by
@code{package-install-upgrade-built-in}.

  By contrast, @code{package-upgrade} and @code{package-upgrade-all}
never consider built-in packages.  If you want to use these commands
for upgrading some built-in packages, you need to upgrade each of
those packages, once, either via @kbd{C-u M-x package-install
@key{RET}}, or by customizing @code{package-install-upgrade-built-in}
to a non-@code{nil} value, and then upgrading the package once via the
package menu or by @code{package-install}.

  If you customize @code{package-install-upgrade-built-in} to a
non-@code{nil} value, be very careful when using commands that update
many packages at once, like @code{package-upgrade-all} and @kbd{U} in
the package menu: those might overwrite built-in packages that you
didn't intent to replace with newer versions from the archives.  Don't
use these bulk commands if you want to update only a small number of
built-in packages.

@cindex package requirements
  A package may @dfn{require} certain other packages to be installed,
because it relies on functionality provided by them.  When Emacs
installs such a package, it also automatically downloads and installs
any required package that is not already installed.  (If a required
package is somehow unavailable, Emacs signals an error and stops
installation.)  A package's requirements list is shown in its help
buffer.

@cindex GNU ELPA
@cindex NonGNU ELPA
  By default, Emacs downloads packages from two archives:
@url{https://elpa.gnu.org/, GNU ELPA} and @url{https://elpa.nongnu.org/,
NonGNU ELPA}.  These are maintained by the Emacs developers and hosted
by the GNU project.  @dfn{GNU ELPA} contains GNU packages that we
consider part of GNU Emacs, but are distributed separately from the core
Emacs.  @dfn{NonGNU ELPA} contains third-party packages whose copyright
has not been assigned to the Free Software Foundation.@footnote{For more
information about copyright assignments, see
@url{https://www.gnu.org/licenses/why-assign.html, Why the FSF Gets
Copyright Assignments from Contributors}.}

@noindent
This is controlled by the variable @code{package-archives}, whose value
is a list of package archives known to Emacs.  Each list element must
have the form @code{(@var{id} . @var{location})}, where @var{id} is the
name of a package archive and @var{location} is the @acronym{URL} or
name of the package archive directory.  You can alter this list if you
wish to use third party package archives---but do so at your own risk,
and use only third parties that you think you can trust!

@cindex base location, package archive
@defopt package-archives
The value of this variable is an alist of package archives recognized
by the Emacs package manager.

Each alist element corresponds to one archive, and should have the
form @code{(@var{id} . @var{location})}, where @var{id} is the name of
the archive (a string) and @var{location} is its @dfn{base location}
(a string).

If the base location starts with @samp{http:} or @samp{https:}, it
is treated as an HTTP(S) URL, and packages are downloaded from this
archive via HTTP(S) (as is the case for the default GNU archive).

Otherwise, the base location should be a directory name.  In this
case, Emacs retrieves packages from this archive via ordinary file
access.  Such local archives are mainly useful for testing.
@end defopt

@anchor{Package Signing}
@cindex package security
@cindex package signing
  The maintainers of package archives can increase the trust that you
can have in their packages by @dfn{signing} them.  They generate a
private/public pair of cryptographic keys, and use the private key to
create a @dfn{signature file} for each package.  With the public key, you
can use the signature files to verify the package creator and make sure
the package has not been tampered with.  Signature verification uses
@uref{https://www.gnupg.org/, the GnuPG package} via the EasyPG
interface (@pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}).
A valid signature is not a cast-iron
guarantee that a package is not malicious, so you should still
exercise caution.  Package archives should provide instructions
on how you can obtain their public key.  One way is to download the
key from a server such as @url{https://pgp.mit.edu/}.
Use @kbd{M-x package-import-keyring} to import the key into Emacs.
Emacs stores package keys in the directory specified by the variable
@code{package-gnupghome-dir}, by default in the @file{gnupg}
subdirectory of @code{package-user-dir}, which causes Emacs to invoke
GnuPG with the option @samp{--homedir} when verifying signatures.
If @code{package-gnupghome-dir} is @code{nil}, GnuPG's option
@samp{--homedir} is omitted.
The public key for the GNU package archive is distributed with Emacs,
in the @file{etc/package-keyring.gpg}.  Emacs uses it automatically.

@vindex package-check-signature
@vindex package-unsigned-archives
  If the user option @code{package-check-signature} is non-@code{nil},
Emacs attempts to verify signatures when you install packages.  If the
option has the value @code{allow-unsigned}, and a usable OpenPGP
configuration is found, signed packages will be checked, but you can
still install a package that is not signed.  If you use some archives
that do not sign their packages, you can add them to the list
@code{package-unsigned-archives}.  (If the value is
@code{allow-unsigned} and no usable OpenPGP is found, this option is
treated as if its value was @code{nil}.)  If the value is @code{t}, at
least one signature must be valid; if the value is @code{all}, all of
them must be valid.

  For more information on cryptographic keys and signing,
@pxref{Top,, GnuPG, gnupg, The GNU Privacy Guard Manual}.
Emacs comes with an interface to GNU Privacy Guard,
@pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}.

@vindex package-pinned-packages
  If you have more than one package archive enabled, and some of them
offer different versions of the same package, you may find the option
@code{package-pinned-packages} useful.  You can add package/archive
pairs to this list, to ensure that the specified package is only ever
downloaded from the specified archive.

@vindex package-archive-priorities
@vindex package-menu-hide-low-priority
  Another option that is useful when you have several package archives
enabled is @code{package-archive-priorities}.  It specifies the
priority of each archive (higher numbers specify higher priority
archives).  By default, archives have the priority of zero, unless
specified otherwise by this option's value.  Packages from
lower-priority archives will not be shown in the menu, if the same
package is available from a higher-priority archive.  (This is
controlled by the value of @code{package-menu-hide-low-priority}.)

  Once a package is downloaded, byte-compiled and installed, it is
made available to the current Emacs session.  Making a package
available adds its directory to @code{load-path} and loads its
autoloads.  The effect of a package's autoloads varies from package to
package.  Most packages just make some new commands available, while
others have more wide-ranging effects on the Emacs session.  For such
information, consult the package's help buffer.

  Installed packages are automatically made available by Emacs in all
subsequent sessions.  This happens at startup, before processing the
init file but after processing the early init file (@pxref{Early Init
File}).  As an exception, Emacs does not make packages available at
startup if invoked with the @samp{-q} or @samp{--no-init-file} options
(@pxref{Initial Options}).

@vindex package-enable-at-startup
  To keep Emacs from automatically making packages available at
startup, change the variable @code{package-enable-at-startup} to
@code{nil}.  You must do this in the early init file, as the variable
is read before loading the regular init file.  Therefore, if you
customize this variable via Customize, you should save your customized
setting into your early init file.  To do this, set or change the value
of the variable @code{custom-file} (@pxref{Saving Customizations}) to
point to your early init file before saving the customized value of
@code{package-enable-at-startup}.

@findex package-quickstart-refresh
@vindex package-quickstart
  If you have many packages installed, you can improve startup times
by setting the user option @code{package-quickstart} to @code{t}.
Setting this option will make Emacs precompute many things instead of
re-computing them on every Emacs startup.  However, if you do this,
then you have to manually run the command
@code{package-quickstart-refresh} when the activations need to be
changed, such as when you change the value of
@code{package-load-list}.

@findex package-activate-all
  If you have set @code{package-enable-at-startup} to @code{nil}, you
can still make packages available either during or after startup.  To
make installed packages available during startup, call the function
@code{package-activate-all} in your init file.  To make installed
packages available after startup, invoke the command @kbd{M-:
(package-activate-all) RET}.

@vindex package-load-list
  For finer control over which packages are made available at startup,
you can use the variable @code{package-load-list}.  Its value should
be a list.  A list element of the form @w{@code{(@var{name}
@var{version})}} tells Emacs to make available version @var{version} of
the package named @var{name}.  Here, @var{version} should be a version
string (corresponding to a specific version of the package), or
@code{t} (which means to make available any installed version), or
@code{nil} (which means no version; this disables the package,
preventing it from being made available).  A list element can also be
the symbol @code{all}, which means to make available the latest
installed version of any package not named by the other list elements.
The default value is just @code{'(all)}.

  For example, if you set @code{package-load-list} to @w{@code{'((muse
"3.20") all)}}, then Emacs only makes available version 3.20 of the
@samp{muse} package, plus any installed version of packages other than
@samp{muse}.  Any other version of @samp{muse} that happens to be
installed will be ignored.  The @samp{muse} package will be listed in
the package menu with the @samp{held} status.

@findex package-recompile
@findex package-recompile-all
  Emacs byte code is quite stable, but it's possible for byte code to
become outdated, or for the compiled files to rely on macros that have
changed in new versions of Emacs.  You can use the command @w{@kbd{M-x
package-recompile}} to recompile a particular package, or
@w{@kbd{M-x package-recompile-all}} to recompile all the packages.  (The
latter command might take quite a while to run if you have many
installed packages.)

@node Package Files
@section Package Files and Directory Layout
@cindex package directory

@cindex package file
@findex package-install-file
  Each package is downloaded from the package archive in the form of a
single @dfn{package file}---either an Emacs Lisp source file, or a tar
file containing multiple Emacs Lisp source and other files.  Package
files are automatically retrieved, processed, and disposed of by the
Emacs commands that install packages.  Normally, you will not need to
deal directly with them, unless you are making a package
(@pxref{Packaging,,,elisp, The Emacs Lisp Reference Manual}).  Should
you ever need to install a package directly from a package file, use
the command @kbd{M-x package-install-file}.

@vindex package-user-dir
  Once installed, the contents of a package are placed in a
subdirectory of @file{~/.emacs.d/elpa/} (you can change the name of
that directory by customizing the variable @code{package-user-dir}).  The
package subdirectory is named @file{@var{name}-@var{version}}, where
@var{name} is the package name and @var{version} is its version
string.

@cindex system-wide packages
@vindex package-directory-list
  In addition to @code{package-user-dir}, Emacs looks for installed
packages in the directories listed in @code{package-directory-list}.
These directories are meant for system administrators to make Emacs
packages available system-wide; Emacs itself never installs packages
there.  The package subdirectories for @code{package-directory-list}
are laid out in the same way as in @code{package-user-dir}.

  Deleting a package (@pxref{Package Menu}) involves deleting the
corresponding package subdirectory.  This only works for packages
installed in @code{package-user-dir}; if told to act on a package in a
system-wide package directory, the deletion command signals an error.

@node Fetching Package Sources
@section Fetching Package Sources
@cindex package development source
@cindex upstream source, for packages
@cindex git source of package @c "git" is not technically correct

  By default @code{package-install} downloads a Tarball from a package
archive and installs its files.  This might be inadequate if you wish
to hack on the package sources and share your changes with others.  In
that case, you may prefer to directly fetch and work on the upstream
source.  This often makes it easier to develop patches and report
bugs.

@findex package-vc-install
@findex package-vc-checkout
  One way to do this is to use @code{package-vc-install}, to fetch the
source code for a package directly from source.  The command will also
automatically ensure that all files are byte-compiled and auto-loaded,
just like with a regular package.  Packages installed this way behave
just like any other package.  You can upgrade them using
@code{package-upgrade} or @code{package-upgrade-all} and delete them
again using @code{package-delete}.  They are even displayed in the
regular package listing.  If you just wish to clone the source of a
package, without adding it to the package list, use
@code{package-vc-checkout}.

  Note that currently, built-in packages cannot be upgraded using
@code{package-vc-install}.

@findex package-report-bug
@findex package-vc-prepare-patch
  With the source checkout, you might want to reproduce a bug against
the current development head or implement a new feature to scratch an
itch.  If the package metadata indicates how to contact the
maintainer, you can use the command @code{package-report-bug} to
report a bug via Email.  This report will include all the user options
that you have customized.  If you have made a change you wish to share
with the maintainers, first commit your changes then use the command
@code{package-vc-prepare-patch} to share it.  @xref{Preparing Patches}.

@findex package-vc-install-from-checkout
@findex package-vc-rebuild
  If you maintain your own packages you might want to use a local
checkout instead of cloning a remote repository.  You can do this by
using @code{package-vc-install-from-checkout}, which creates a symbolic link
from the package directory (@pxref{Package Files}) to your checkout
and initializes the code.  Note that you might have to use
@code{package-vc-rebuild} to repeat the initialization and update the
autoloads.

@subsection Specifying Package Sources
@cindex package specification
@cindex specification, for source packages

  To install a package from source, Emacs must know where to get the
package's source code (such as a code repository) and basic
information about the structure of the code (such as the main file in
a multi-file package).  A @dfn{package specification} describes these
properties.

  When supported by a package archive (@pxref{Package
Archives,,,elisp, The Emacs Lisp Reference Manual}), Emacs can
automatically download a package's specification from said archive.
If the first argument passed to @code{package-vc-install} is a symbol
naming a package, then Emacs will use the specification provided by
the archive for that package.

@example
@group
;; Emacs will download BBDB's specification from GNU ELPA:
(package-vc-install 'bbdb)
@end group
@end example

  The first argument to @code{package-vc-install} may also be a
package specification.  This allows you to install source packages
from locations other than the known archives listed in the user option
@code{package-archives}.  A package specification is a list of the
form @code{(@var{name} . @var{spec})}, in which @var{spec} should be a
property list using any of the keys in the table below.

For definitions of basic terms for working with code repositories and
version control systems, see @ref{VCS Concepts,,,emacs, The GNU Emacs
Manual}.

@table @code
@item :url
A string providing the URL that specifies the repository from which to
fetch the package's source code.

@item :branch
A string providing the revision of the code to install.  Do not
confuse this with a package's version number.

@item :lisp-dir
A string providing the repository-relative name of the directory to
use for loading the Lisp sources, which defaults to the root directory
of the repository.

@item :main-file
A string providing the main file of the project, from which to gather
package metadata.  If not given, the default is the package name with
".el" appended to it.

@item :doc
A string providing the repository-relative name of the documentation
file from which to build an Info file.  This can be a Texinfo file or
an Org file.

@item :make
A string or list of strings providing the target or targets defined in
the repository Makefile which should run before building the Info file.
Only takes effect when @code{package-vc-allow-build-commands} is
non-@code{nil}.

@item :shell-command
A string providing the shell command to run before building the Info
file.  Only takes effect when @code{package-vc-allow-build-commands}
is non-@code{nil}.

@item :vc-backend
A symbol naming the VC backend to use for downloading a copy of the
package's repository (@pxref{Version Control Systems,,,emacs, The GNU
Emacs Manual}).  If omitted, Emacs will attempt to make a guess based
on the provided URL, or, failing that, the process will fall back onto
the value of @code{package-vc-default-backend}.
@end table

@example
@group
;; Specifying information manually:
(package-vc-install
  '(bbdb :url "https://git.savannah.nongnu.org/git/bbdb.git"
         :lisp-dir "lisp"
         :doc "doc/bbdb.texi"))
@end group
@end example