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 OS X, 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 systemd user service for automatically starting the Emacs daemon.

Emacs can be installed in the normal way for Nix (see ). In addition, a NixOS service can be enabled.

Nixpkgs defines several basic Emacs packages. The following are attributes belonging to the pkgs set: emacs emacs25 The latest stable version of Emacs 25 using the GTK+ 2 widget toolkit. emacs25-nox Emacs 25 built without any dependency on X11 libraries. emacs24Macport Emacs 24 with the "Mac port" patches, providing a more native look and feel under OS X. If those aren't suitable, then the following imitation Emacs editors are also available in Nixpkgs: Zile, mg, Yi.

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 (package.el) from Emacs Lisp Package Archive (ELPA), MELPA, MELPA Stable, and Org ELPA. 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. This documentation describes the new Emacs packages framework in NixOS 16.03 (emacsPackagesNg) which should not be confused with the previous and deprecated framework (emacs24Packages). 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 emacs.nix file such as: /* 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 */ { pkgs ? import <nixpkgs> {} }: let myEmacs = pkgs.emacs; emacsWithPackages = (pkgs.emacsPackagesNgGen myEmacs).emacsWithPackages; in emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [ magit # ; Integrate git <C-x g> zerodark-theme # ; Nicolas' theme ]) ++ (with epkgs.melpaPackages; [ undo-tree # ; <C-x u> to show the undo tree zoom-frm # ; increase/decrease font size for all buffers %lt;C-x C-+> ]) ++ (with epkgs.elpaPackages; [ auctex # ; LaTeX mode beacon # ; highlight my cursor when scrolling nameless # ; hide current package name everywhere in elisp code ]) ++ [ pkgs.notmuch # From main packages set ]) The first non-comment line in this file ({ pkgs ? ... }) indicates that the whole file represents a function. 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. This generates an emacsWithPackages function. It takes a single argument: a function from a package set to a list of packages (the packages that will be available in Emacs). The rest of the file specifies the list of packages to install. In the example, two packages (magit and zerodark-theme) are taken from MELPA stable. Two packages (undo-tree and zoom-frm) are taken from MELPA. Three packages are taken from GNU ELPA. notmuch is taken from a nixpkgs derivation which contains an Emacs mode. The result of this configuration will be an emacs command which launches Emacs with all of your chosen packages in the load-path. You can check that it works by executing this in a terminal: $ nix-build emacs.nix $ ./result/bin/emacs -q and then typing M-x package-initialize. Check that you can use all the packages you want in this Emacs instance. For example, try switching to the zerodark theme through M-x load-theme <RET> zerodark <RET> y. A few popular extensions worth checking out are: auctex, company, edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile, and yasnippet. The list of available packages in the various ELPA repositories can be seen with the following commands: " -qaP -A emacsPackagesNg.elpaPackages nix-env -f "" -qaP -A emacsPackagesNg.melpaPackages nix-env -f "" -qaP -A emacsPackagesNg.melpaStablePackages nix-env -f "" -qaP -A emacsPackagesNg.orgPackages ]]> If you are on NixOS, you can install this particular Emacs for all users by adding it to the list of system packages (see ). Simply modify your file configuration.nix to make it contain: In this case, the next nixos-rebuild switch will take care of adding your emacs to the PATH environment variable (see ). If you are not on NixOS or want to install this particular Emacs only for yourself, you can do so by adding it to your ~/.nixpkgs/config.nix (see Nixpkgs manual): In this case, the next nix-env -f '<nixpkgs>' -iA myemacs will take care of adding your emacs to the PATH environment variable.

If you want, you can tweak the Emacs package itself from your emacs.nix. For example, if you want to have a GTK+3-based Emacs instead of the default GTK+2-based binary and remove the automatically generated emacs.desktop (useful is you only use emacsclient), you can change your file emacs.nix in this way: {} }: let myEmacs = pkgs.lib.overrideDerivation (pkgs.emacs.override { # Use gtk3 instead of the default gtk2 withGTK3 = true; withGTK2 = false; }) (attrs: { # I don't want emacs.desktop file because I only use # emacsclient. postInstall = attrs.postInstall + '' rm $out/share/applications/emacs.desktop ''; }); in [...] ]]> After building this file as shown in , you will get an GTK3-based Emacs binary pre-loaded with your favorite packages.

NixOS provides an optional systemd service which launches Emacs daemon with the user's login session. Source: modules/services/editors/emacs.nix

To install and enable the systemd user service for Emacs daemon, add the following to your configuration.nix: The services.emacs.package option allows a custom derivation to be used, for example, one created by emacsWithPackages. Ensure that the Emacs server is enabled for your user's Emacs configuration, either by customizing the server-mode variable, or by adding (server-start) to ~/.emacs.d/init.el. To start the daemon, execute the following: $ nixos-rebuild switch # to activate the new configuration.nix $ systemctl --user daemon-reload # to force systemd reload $ systemctl --user start emacs.service # to start the Emacs daemon The server should now be ready to serve Emacs clients.

Ensure that the emacs server is enabled, either by customizing the server-mode variable, or by adding (server-start) to ~/.emacs. To connect to the emacs daemon, run one of the following:

If services.emacs.defaultEditor is true, the EDITOR variable will be set to a wrapper script which launches emacsclient. Any setting of EDITOR in the shell config files will override services.emacs.defaultEditor. To make sure EDITOR refers to the Emacs wrapper script, remove any existing EDITOR assignment from .profile, .bashrc, .zshenv or any other shell config file. If you have formed certain bad habits when editing files, these can be corrected with a shell alias to the wrapper script: alias vi=$EDITOR

In general, systemd user services are globally enabled by symlinks in /etc/systemd/user. In the case where Emacs daemon is not wanted for all users, it is possible to install the service but not globally enable it: To enable the systemd user service for just the currently logged in user, run: systemctl --user enable emacs This will add the symlink ~/.config/systemd/user/emacs.service.

The Emacs init file should be changed to load the extension packages at startup: After the declarative emacs package configuration has been tested, previously downloaded packages can be cleaned up by removing ~/.emacs.d/elpa (do make a backup first, in case you forgot a package).

Of interest may be melpaPackages.nix-mode, which provides syntax highlighting for the Nix language. This is particularly convenient if you regularly edit Nix files.

You can use woman to get completion of all available man pages. For example, type M-x woman <RET> nixos-rebuild <RET>.

Emacs includes nXML, a major-mode for validating and editing XML documents. When editing DocBook 5.0 documents, such as this one, nXML needs to be configured with the relevant schema, which is not included. To install the DocBook 5.0 schemas, either add pkgs.docbook5 to environment.systemPackages (NixOS), or run nix-env -i pkgs.docbook5 (Nix). Then customize the variable rng-schema-locating-files to include ~/.emacs.d/schemas.xml and put the following text into that file: ]]>