This document explains how to use Cask, and provides a reference of its commands and options.
Start by creating a file named
Cask in the project root. Use
cask init command to create a
containing boilerplate code:
$ cask init [--dev]
cask init --dev, if the project is for package development!
If you are using Cask for your Emacs configuration, add this to your
(require 'cask "~/.cask/cask.el") (cask-initialize)
Or if you installed Cask via Homebrew:
(require 'cask "/usr/local/share/emacs/site-lisp/cask/cask.el") (cask-initialize)
To install all dependencies, run:
$ cask install
This will create a directory called
.cask and install all dependencies into
By default, packages are installed for the default Emacs, i.e., the one behind
emacs command. To pick a different Emacs, set the environment variable
EMACS to the command name or executable path of the Emacs to use:
$ EMACS="emacs24.1" cask command
Note that installed dependencies are scoped on the version of Emacs. So when switching between versions you will have to install the dependencies for each:
$ EMACS="emacs24.5" cask install
There are, unfortunately, circumstances under which Emacs itself
EMACS variable in a way which conflicts with
cask, in which case you can use the environment variable
CASK_EMACS instead. Specifically, this problem effects:
M-x shell or
M-x term, for Emacs-25
and Emacs-26 only for
Commands and options¶
The general syntax of the cask program is as follows:
cask [GLOBAL-OPTIONS] [COMMAND] [COMMAND-OPTIONS] [COMMAND-ARGUMENTS]
cask [GLOBAL-OPTIONS] exec [COMMAND] [ARGUMENTS ...]
cask [GLOBAL-OPTIONS] emacs [ARGUMENTS ...]
cask [GLOBAL-OPTIONS] eval [FORM]
FORM as a lisp form with a proper
$PATH (see cask path)
and $EMACSLOADPATH (see cask load-path). The return value of the form
is not printed directly:
FORM must print to the standard out or error
cask [GLOBAL-OPTIONS] help [COMMAND]
Show help about Cask, or a given
cask [GLOBAL-OPTIONS] info
Show information about the project, such as name, description and version.
cask [GLOBAL-OPTIONS] init [--dev]
Cask-file in the current directory.
If the project is for package development, use the
Add additional code to the
Caskfile, which is specific to Emacs Lisp packages.
cask [GLOBAL-OPTIONS] [install]
Install all dependencies of the project. This is the default command.
cask [GLOBAL-OPTIONS] list
List all run-time and development dependencies.
cask [GLOBAL-OPTIONS] load-path
Print the load path containing the dependencies of the current project, in
proper format for the
EMACSLOADPATH environment variable.
cask exec automatically runs its commands with the proper load-path.
cask [GLOBAL-OPTIONS] outdated
Show all outdated dependencies.
cask [GLOBAL-OPTIONS] pkg-file
Write a package descriptor file to
project-pkg.el in the project root.
project is the project name, as declared in the
Cask file. See
Multi-file Packages(elisp) for details.
cask [GLOBAL-OPTIONS] package-directory
Print path to package directory, where all dependencies are installed.
Currently, this is
is the value of the
emacs-version variable in Emacs.
cask [GLOBAL-OPTIONS] path
PATH environment variable of this project.
PATH of a project contains the binary directories of all
dependencies, prepended to the
PATH inherited from the current shell.
The binary directory of a package is the
bin/ subdirectory of the package.
cask exec uses the
PATH returned by this command when running
cask [GLOBAL-OPTIONS] update
Update all dependencies installed in the project.
cask [GLOBAL-OPTIONS] upgrade-cask
Upgrade Cask and all its dependencies.
cask [GLOBAL-OPTIONS] version
Print version of the current package.
cask [GLOBAL-OPTIONS] files
Print the list of all package files.
cask [GLOBAL-OPTIONS] build
Byte compile all Emacs Lisp files in the package. The resulting byte code is
written to the original path, with the extension replaced by
cask [GLOBAL-OPTIONS] package [DISTDIR]
Build a package artefact, and put it into the given DISTDIR, defaulting
For single-file packages, this command merely copies the corresponding file to
DISTDIR, under the correct filename
For multi-file packages, this command creates a TAR archive containing the
package-version.tar. The TAR archive contains an
appropriate package descriptor as generated by cask pkg-file.
files of the package contain
.texinfo files and if
makeinfo is available, these are compiled to Info before inclusion in
the package, to allow for online reading of the manual in Emacs.
The following options are available on all Cask commands:
Set Emacs proxy for HTTP and HTTPS:
$ cask --proxy "localhost:8888" install
Set Emacs proxy for HTTP only.
Set Emacs proxy for HTTPS only.
Do not use a proxy for any URL matching pattern.
pattern is an Emacs regular expression.
Print Cask’s version.
Enable debug information.
directory/Caskinstead of the
Caskfile in the current directory.
Show all output from
The command name or executable path of Emacs. Cask will use this Emacs in its commands, i.e. byte-compile files with this Emacs, install packages for this Emacs, and run commands from packages installed for this Emacs.
If empty, Cask tries to find a reasonable default. On OS X, Cask tries the following Emacsen, in this order:
On other Unix variants, e.g. Linux, Cask will simply use
As EMACS, but takes precedence over it. This is most useful for launching Cask inside Emacs which sometimes resets EMACS to other values.