Skip to content
Check Emacs Lisp packages in a clean environment
Emacs Lisp Shell Nix
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Emacs Package Checker lets you quickly configure typical linters (i.e. package-lint, byte-compile, and checkdoc) for your Emacs package.

There are existing solutions in this field like emake.el and makel. Emacs Package Checker is not any more capable than those existing solutions, but it is based on Nix package manager and runs tests in a pure, sandboxed environment. This is useful for testing Emacs packages on local machines.

Configuration for a single package

Note: The current API is subject to change in the next update, so please don’t use it in production.

First you have to create a configuration file in your package repository. The recommended file name is default.nix, but it can be any name with .nix suffix.

The following is an example from poly-vue package:

{ pkgs ? import <nixpkgs> {}, emacs ? pkgs.emacs25 }:
  check-package = import (builtins.fetchGit {
    url = "";
    ref = "master";
    rev = "1553d9f6c8d61e8f455f22e4a1d0743bc8cd48a9";
in check-package {
  inherit emacs pkgs;
  name = "emacs-poly-vue";
  src = ./.;
  targetFiles = ["poly-vue.el"];
  emacsPackages = epkgs: (with epkgs.melpaPackages; [
  • An optional argument emacs is the Emacs package in nixpkgs used to byte-compile Emacs Lisp files. For details, refer to a subsection in NixOS manual.
  • rev must be the hash of this repository.
  • name can be any string accepted as a file name. It is used as part of directory names.
  • src should point to the directory containing Emacs Lisp files.
  • targetFiles is a list of Emacs Lisp files to check.
  • emacsPackages is a function that returns a list of Emacs Lisp packages required to build the Emacs Lisp files in targetFiles. This should be done as in NixOS.

Checking the package locally

If the name of the configuration file is default.nix, you can check the package with the following command:

# Run checkdoc
nix-build --no-out-link --quiet -A checkdoc
# Byte-compile
nix-build --no-out-link --quiet -A byte-compile
# Package-lint
nix-shell --pure --quiet -A package-lint
  • checkdoc and byte-compile can be run in nix-build, but package-lint must be run in nix-shell. This is because package-lint requires an internet connection to check if packages are installable, but nix-build forbidden that.
  • --no-out-link is need to prevent nix-build from creating result directory in the repository.
  • When --pure is given as an argument, nix-shell runs the command in a sandbox.
  • --quiet flag suppress messages related to Nix.

If you have set NIX_BUILD_SHELL environment variable to something like zsh, you may have to unset it temporarily when you run nix-shell.

If the file name is something other than default.nix, then you have to append the file name to each command line.

Travis configuration

A minimal configuration for TravisCI is as follows:

language: nix

  - nix-build -A byte-compile --no-out-link --quiet
  - nix-build -A checkdoc --no-out-link --quiet
  - nix-shell -A package-lint --pure --quiet

    - /nix/store
    - /dev/shm/package-lint

Optionally, you can add matrix to run tests on multiple configurations.


Files created on the file system

  • Files are built in the Nix store, which is located in /nix/store by default. You can remove unnecessary files by running nix-store --gc.
  • Package archives are stored in a directory in /dev/shm/package-lint/elpa when you run package-lint. You can safely remove them after the process is finished.

Setting the Emacs version at runtime

In the configuration, an Emacs package specified as emacs in the input argument is used to build the Emacs package, and the value after ? is used as its default value. You can override the argument from the command line.

To use the latest stable version for byte-compiling the package, add the following arguments to the command line:

--arg emacs "(import <nixpkgs> {}).emacs"

The entire command line will be as follows:

nix-build --no-out-link --quiet -A byte-compile --arg emacs "(import <nixpkgs> {}).emacs"

To use Emacs 25:

nix-build --no-out-link --quiet -A byte-compile --arg emacs "(import <nixpkgs> {}).emacs25"


GPL v3

You can’t perform that action at this time.