nano-emacs: A Minimal Emacs Configuration Built for Consistent Visual Design

The Design Philosophy Behind nano-emacs

nano-emacs is grounded in a specific argument about editor design. The README references 'On the design of text Editors,' published on arXiv in 2020 (arXiv:2008.06030), as the source of the principles behind the configuration. That paper argues for restraint: fewer visual elements, consistent colors, and careful typography rather than feature accumulation.

The README states the philosophy directly: 'to stick as much as possible to vanilla emacs without introducing too much dependencies (or none if possible) and to keep it modular enough.' This positions nano-emacs against frameworks like Doom Emacs or Spacemacs, which install many packages by default and provide opinionated keybindings across dozens of modes. nano-emacs makes no assumption about which modes the user runs; it defines a set of faces and a header-line modeline and leaves the rest alone.

The intended use case, per the README, is for users to copy the parts they are interested in and merge them into their own Emacs configuration rather than running the full configuration as a unit. This makes nano-emacs more of a design reference than a turnkey setup.

How to Install nano-emacs: Quick Test and Two Permanent Paths

The README provides three installation paths. The quickest is a temporary test that does not modify any existing configuration:

$ emacs -q -l nano.el

This command starts Emacs with no user configuration loaded (`-q`) and then loads nano.el from inside the cloned repository. It lets users evaluate the look and feel before committing to any changes. After testing, the user can choose between the two permanent installation paths.

The first permanent path is manual: merge the contents of nano.el into an existing Emacs configuration file after adding the nano-emacs repository to the load path. The README notes that the only mandatory module is `nano-faces`, which defines the six faces used across the rest of the configuration.

The second permanent path uses the `straight.el` package manager:

(straight-use-package
  '(nano :type git :host github :repo "rougier/nano-emacs"))

Once installed via straight.el, the user can either `(require 'nano)` to load the default configuration or load individual modules selectively. The mandatory module constraint applies here too: calling any nano module before `(nano-faces)` produces faces that are not yet defined.

The Module System: Mandatory, Optional, and Experimental

nano-emacs is organized as a set of independent Emacs Lisp files. Two are mandatory. `nano-base-colors.el` defines the fundamental color values; `nano-faces.el` defines six faces that the rest of the modules derive from. The README recommends loading any existing Emacs theme before loading nano-faces, so that the theme's colors take precedence over nano's defaults.

The optional modules cover specific concerns. `nano-layout.el` sets frame font, fringes, and margins. `nano-modeline.el` defines a header line that is mode-dependent and hides the traditional bottom modeline. `nano-defaults.el` provides a set of default settings for Emacs that differ from the GNU defaults. `nano-session.el` saves the session between runs. `nano-bindings.el` adds a reduced keybinding set for common commands.

`nano-theme.el` derives faces for popular Emacs modes from the six nano faces. A user who wants only selected mode support can call individual `nano-theme--` functions rather than calling `(nano-theme)` wholesale.

The experimental modules include `nano-mu4e.el` for the mu4e email client, `nano-minibuffer.el` which uses the `mini-frame` package, `nano-command.el` for a header-line command prompt, and `nano-agenda.el` for an interactive org-mode mini agenda. These modules are marked experimental and may change without notice.

Font Requirements and Customization

nano-emacs requires two fonts to be installed on the system before loading: Roboto Mono and Fira Code. The README states there are no other dependencies, but this font requirement is a genuine installation step on systems that do not have these fonts. Google Fonts is the original distribution source for both.

Once loaded, the font can be changed through three variables that must be set before `(nano-faces)` and `(nano-theme)` are called:

(setq nano-font-family-monospaced "Roboto Mono")

This sets the default monospaced face. The README notes that fonts without proper light or bold weights will lose key design features, since nano-emacs uses weight variations to distinguish UI elements rather than color alone.

(setq nano-font-family-proportional nil)

Setting this variable to a proportional font name enables `variable-width-mode` and `mixed-pitch-mode`. Leaving it nil uses the monospaced font for all text.

(setq nano-font-size 14)

This sets the size for most faces. The README warns that changing any of these variables after `(nano-faces)` has run requires calling `(nano-faces)` and `(nano-theme)` again for the changes to take effect.

Color System: Material Light and Nord Dark

nano-emacs ships two theme files for the base colors: `nano-theme-light.el` and `nano-theme-dark.el`. The light theme derives from Material colors (material.io) and the dark theme from Nord (nordtheme.com). These color palettes are embedded in the base color module rather than being installed as separate Emacs themes.

A user who wants different colors can override the base color values in `nano-base-colors.el`. The module structure makes this possible without touching the face definitions, since all faces in nano-emacs derive from the six fundamental faces defined in `nano-faces.el`, which in turn reference the base colors. Changing a base color propagates through all derived faces without requiring individual face overrides.

`nano-colors.el` provides access to three color palettes: Open Colors, Material Colors, and Nord Colors. These are available as functions for use in custom configuration code rather than being applied automatically.

The light and dark themes are optional, not mandatory. Users who want to use a different Emacs theme as the foundation can skip both theme files and load only `nano-base-colors.el` and `nano-faces.el`, which will inherit colors from whatever theme is already active.

Limitations and Comparison with Doom Emacs

nano-emacs' modular structure is its main strength and its main limitation. Because the project is designed to be merged into an existing configuration rather than used as a complete setup, users who want a fully working editor out of the box will find it underwhelming. There are no language server configurations, no project management integrations, no completion framework, and no package management beyond the optional `nano-counsel.el` module for the counsel package.

The header-line modeline from `nano-modeline.el` is mode-dependent. The README notes it 'takes care of hiding the modeline when necessary,' but it does not document which modes are covered, which means users running uncommon modes may see the default Emacs modeline in those buffers.

Doom Emacs is a well-known alternative that takes a framework approach: it installs many packages by default, provides vim-style keybindings, and configures language servers for common programming languages. Doom Emacs is a faster path to a fully-functional editor on any language. nano-emacs is faster only in the sense of loading fewer packages; it requires the user to build all functionality on top of the six faces it provides.

The last push to nano-emacs was on 2026-06-12. There are no GitHub releases; versions are tracked through git commits. The project is licensed under GPL-3.0, which permits modification and redistribution under the same terms.

Editorial conclusion

nano-emacs is the right choice for Emacs users who want a coherent visual design without adopting a full configuration framework. It works best when used as a source of ideas to incorporate into an existing configuration rather than as a drop-in replacement for one. The font requirement is a real constraint: Roboto Mono and Fira Code must be installed on the system before loading the configuration, or the visual design degrades. The light and dark themes depend on Material and Nord color palettes that are built into the module rather than being configurable by name; customizing colors requires editing the base color module directly. The last push was on 2026-06-12.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. rougier/nano-emacs on GitHub