# Emacs {#module-services-emacs}

<!--
    Documentation contributors:
      Damien Cassou @DamienCassou
      Thomas Tuegel @ttuegel
      Rodney Lorrimar @rvl
      Adam Hoese @adisbladis
  -->

[Emacs](https://www.gnu.org/software/emacs/) is an
extensible, customizable, self-documenting real-time display editor — and
more. At its core is an interpreter for Emacs Lisp, a dialect of the Lisp
programming language with extensions to support text editing.

Emacs runs within a graphical desktop environment using the X Window System,
but works equally well on a text terminal. Under
macOS, a "Mac port" edition is available, which
uses Apple's native GUI frameworks.

Nixpkgs provides a superior environment for
running Emacs. It's simple to create custom builds
by overriding the default packages. Chaotic collections of Emacs Lisp code
and extensions can be brought under control using declarative package
management. NixOS even provides a
{command}`systemd` user service for automatically starting the Emacs
daemon.

## Installing Emacs {#module-services-emacs-installing}

Emacs can be installed in the normal way for Nix (see
[](#sec-package-management)). In addition, a NixOS
*service* can be enabled.

### The Different Releases of Emacs {#module-services-emacs-releases}

Nixpkgs defines several basic Emacs packages.
The following are attributes belonging to the {var}`pkgs` set:

  {var}`emacs`
  : The latest stable version of Emacs using the [GTK 2](http://www.gtk.org)
    widget toolkit.

  {var}`emacs-nox`
  : Emacs built without any dependency on X11 libraries.

  {var}`emacsMacport`
  : Emacs with the "Mac port" patches, providing a more native look and
    feel under macOS.

If those aren't suitable, then the following imitation Emacs editors are
also available in Nixpkgs:
[Zile](https://www.gnu.org/software/zile/),
[mg](http://homepage.boetes.org/software/mg/),
[Yi](http://yi-editor.github.io/),
[jmacs](https://joe-editor.sourceforge.io/).

### Adding Packages to Emacs {#module-services-emacs-adding-packages}

Emacs includes an entire ecosystem of functionality beyond text editing,
including a project planner, mail and news reader, debugger interface,
calendar, and more.

Most extensions are gotten with the Emacs packaging system
({file}`package.el`) from
[Emacs Lisp Package Archive (ELPA)](https://elpa.gnu.org/),
[MELPA](https://melpa.org/),
[MELPA Stable](https://stable.melpa.org/), and
[Org ELPA](http://orgmode.org/elpa.html). Nixpkgs is
regularly updated to mirror all these archives.

Under NixOS, you can continue to use
`package-list-packages` and
`package-install` to install packages. You can also
declare the set of Emacs packages you need using the derivations from
Nixpkgs. The rest of this section discusses declarative installation of
Emacs packages through nixpkgs.

The first step to declare the list of packages you want in your Emacs
installation is to create a dedicated derivation. This can be done in a
dedicated {file}`emacs.nix` file such as:

::: {.example #ex-emacsNix}
### Nix expression to build Emacs with packages (`emacs.nix`)

```nix
/*
This is a nix expression to build Emacs and some Emacs packages I like
from source on any distribution where Nix is installed. This will install
all the dependencies from the nixpkgs repository and build the binary files
without interfering with the host distribution.

To build the project, type the following from the current directory:

$ nix-build emacs.nix

To run the newly compiled executable:

$ ./result/bin/emacs
*/

# The first non-comment line in this file indicates that
# the whole file represents a function.
{ pkgs ? import <nixpkgs> {} }:

let
  # The let expression below defines a myEmacs binding pointing to the
  # current stable version of Emacs. This binding is here to separate
  # the choice of the Emacs binary from the specification of the
  # required packages.
  myEmacs = pkgs.emacs;
  # This generates an emacsWithPackages function. It takes a single
  # argument: a function from a package set to a list of packages