Table of Content:
The Elvish Package Manager (
epm) is a module bundled with Elvish for managing third-party packages.
In Elvish terminology, a module is a
.elv file that can be imported with the
use command, while a package is a collection of modules that are usually kept in the same repository as one coherent project and may have interdependencies. The Elvish language itself only deals with modules; the concept of package is a matter of how to organize modules.
go command, Elvish does not have a central registry of packages. A package is simply identified by the URL of its code repository, e.g. github.com/elves/sample-pkg. To install the package, one simply uses the following:
epm knows out-of-the-box how to manage packages hosted in GitHub, BitBucket and GitLab, and requires the
git command to be available. It can also copy files via
rsync from arbitrary locations (see Custom package domains for details).
Once installed, modules in this package can be imported with
use github.com/elves/sample-pkg/.... This package has a module named
sample-mod containing a function
sample-fn, and can be used like this:
~> use github.com/elves/sample-pkg/sample-mod
This is a sample function in a sample module in a sample package
The next section describes functions in the
epm module, using the same notation as the doc for the builtin module.
epm:install &silent-if-installed=$false $pkg...
Install the named packages. By default, if a package is already installed, a message will be shown. This can be disabled by passing
&silent-if-installed=$true, so that already-installed packages are silently ignored.
Return an array with all installed packages.
epm:list can be used as an alias for
Returns a boolean value indicating whether the given package is installed.
Returns a hash containing the metadata for the given package. Metadata for a package includes the following base attributes:
name: name of the package
installed: a boolean indicating whether the package is currently installed
method: method by which it was installed (
src: source URL of the package
dst: where the package is (or would be) installed. Note that this attribute is returned even if
Additionally, packages can define arbitrary metadata attributes in a file called
metadata.json in their top directory. The following attributes are recommended:
description: a human-readable description of the package
maintainers: an array containing the package maintainers, in
homepage: URL of the homepage for the package, if it has one.
Pretty print the available metadata of the given package.
Uninstall named packages.
Upgrade named packages. If no package name is given, upgrade all installed packages.
Custom package domains
Package names in
epm have the following structure:
domain is usually the hostname from where the package is to be fetched, such as
path can have one or more components separated by slashes. Usually, the full name of the package corresponds with the URL from where it can be fetched. For example, the package hosted at https://github.com/elves/sample-pkg is identified as
Packages are stored under
~/.elvish/lib/ in a path identical to their name. For example, the package mentioned above is stored at
Each domain must be configured with the following information:
The method to use to fetch packages from the domain. The two supported methods are
The number of directory levels under the domain directory in which the packages are found. For example, for
github.comthe number of levels is 2, since package paths have two levels (e.g.
elves/sample-pkg). All packages from a given domain have the same number of levels.
Depending on the method, other attributes are needed:
protocolattribute, which can be
http, and determines how the URL is constructed.
locationattribute, which must be a valid source directory recognized by the
epm includes default domain configurations for
bitbucket.org. These three domains share the same configuration:
You can define your own domain by creating a file named
epm-domain.cfg in the appropriate directory under
~/.elvish/lib/. For example, if you want to define an
elvish-dev domain which installs packages from your local
~/dev/elvish/ directory, you must create the file
~/.elvish/lib/elvish-dev/epm-domain.cfg with the following JSON content:
You can then install any directory under
~/dev/elvish/ as a package. For example, if you have a directory
~/dev/elvish/utilities/, the following command will install it under
When you make any changes to your source directory,
epm:upgrade will synchronize those changes to