Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 38 ยท Configuration and Elisp

The Emacs Init File, early-init.el and the Customize Interface

Learn where Emacs looks for your init file, what early-init.el is for, how Customize writes settings, and how to debug a broken configuration safely.

Emacs is configured by code. When it starts, it reads a file of Emacs Lisp, the init file, and runs it before showing you anything. Every theme, key binding and package setting you will meet in later lessons lives there. In this lesson you learn where that file goes, what else Emacs reads at startup, how the built-in Customize interface edits settings for you, and how to recover when you break something.

Emacs itself is a desktop program, so we cannot run it on this page. Instead, the examples use small JavaScript stand-ins that model the rules (file search order, reading setq forms). They are labelled as stand-ins; the Emacs commands and Lisp snippets in code blocks are the real thing.

Where the init file lives

Emacs looks for a personal init file in a fixed list of places and uses the first one it finds:

  1. ~/.emacs
  2. ~/.emacs.el
  3. ~/.emacs.d/init.el
  4. ~/.config/emacs/init.el (the XDG location, supported since Emacs 27)

On Windows, ~ is your user profile folder unless the HOME environment variable says otherwise. The folder that holds init files and package data is stored in the variable user-emacs-directory. Most people choose ~/.emacs.d/init.el because the folder can also hold packages, caches and extra Lisp files, and because it works as a single Git repository.

JS Stand-in: which init file wins?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The third scenario shows a classic surprise: a forgotten ~/.emacs file silently hides your init.el. If a configuration "does nothing", check which file Emacs really loaded. Inside Emacs, the variable user-init-file holds the answer: press C-h v (describe-variable), type user-init-file and press RET.

Emacs 29 added a command-line option, --init-directory DIR, that starts Emacs with a completely different configuration folder. It is handy for trying someone else's configuration without touching your own.

early-init.el

Since Emacs 27 there is a second file, early-init.el, in the same folder as init.el. Emacs reads it before it creates the first window and before the package system starts. It is meant for a few things that must happen early:

  • turning off package auto-loading ((setq package-enable-at-startup nil)) if you use another package manager;
  • removing toolbars and scroll bars before they flash on the screen;
  • raising the garbage-collection threshold to speed up loading;
  • setting the frame size so the window does not resize while starting.
ELISP
;; ~/.emacs.d/early-init.el
(setq package-enable-at-startup nil)
(push '(menu-bar-lines . 0) default-frame-alist)
(push '(tool-bar-lines . 0) default-frame-alist)
(push '(vertical-scroll-bars) default-frame-alist)

Put almost everything else in init.el. A short early-init.el is a good sign.

A first init file

An init file is just Lisp, evaluated top to bottom. Here is a small but realistic example:

ELISP
;;; init.el --- my configuration  -*- lexical-binding: t; -*-

(setq inhibit-startup-screen t)        ; skip the welcome buffer
(setq make-backup-files nil)           ; no file~ clutter
(setq-default indent-tabs-mode nil)    ; spaces, not tabs
(column-number-mode 1)                 ; show the column in the mode line
(global-display-line-numbers-mode 1)
(load-theme 'modus-vivendi t)          ; built-in dark theme

The first line is a header comment. The -*- lexical-binding: t; -*- cookie switches the file to lexical scoping, which is what modern Emacs Lisp expects (see functions and control flow). setq assigns a variable; setq-default sets the value that buffers use unless they override it. Functions ending in -mode are modes: calling them with 1 turns them on, with -1 turns them off.

The Customize interface

Emacs has a built-in settings editor, started with M-x customize or, to find an option by word, M-x customize-variable, M-x customize-group and M-x customize-themes. It presents each option as a form with a value, a documentation string and buttons such as Apply and Save.

When you save, Emacs does not edit your own code. It appends a block like this to the end of the init file:

ELISP
(custom-set-variables
 ;; custom-set-variables was added by Custom.
 '(column-number-mode t)
 '(inhibit-startup-screen t))
(custom-set-faces
 ;; custom-set-faces was added by Custom.
 '(default ((t (:height 130)))))

You should not hand-edit that block, and it is easy to lose track of. A common tidy-up is to send it to a separate file:

ELISP
(setq custom-file (expand-file-name "custom.el" user-emacs-directory))
(load custom-file 'noerror 'nomessage)

Now Customize writes to custom.el, and init.el stays yours. Customize is also an excellent discovery tool: browse M-x customize-group RET editing RET to learn what can be tuned, then copy the settings you like into init.el as setq or, better, setopt (Emacs 29+), which runs the option's setter the way Customize would.

JS Stand-in: list the settings in an init file

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Debugging a broken configuration

Because the init file is code, a typo can stop the rest from loading. Emacs gives you three safety nets:

  • emacs -Q starts with no init file and no site customizations. If the problem disappears, your configuration is the cause.
  • emacs --debug-init opens a backtrace at the exact form that failed.
  • M-x toggle-debug-on-error shows a backtrace for errors while you work.

If an error occurs, Emacs still opens, with a message such as An error occurred while loading init.el. Fix the form, then evaluate the file again with M-x load-file RET ~/.emacs.d/init.el RET, or restart. For later bisecting techniques see troubleshooting and performance.

Keep your configuration in Git from day one. When something breaks after an edit, git diff tells you exactly which line to blame.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file does Emacs read before it creates the first frame and starts the package system?

    early-init.el (Emacs 27+) is read first, so it is the place for settings that must apply before the window and packages appear.
  2. 2. You have both ~/.emacs and ~/.emacs.d/init.el. Which one does Emacs load?

    Emacs uses the first file it finds; ~/.emacs precedes ~/.emacs.d/init.el, so the latter is ignored.
  3. 3. What does the option to move Customize output to a separate file look like?

    Setting custom-file and loading it keeps the machine-written block out of init.el.
  4. 4. Which command-line flag starts Emacs without reading your init file?

    emacs -Q skips the init file; --debug-init instead keeps it and shows a backtrace on error.

Summary

  • Emacs reads the first existing file of ~/.emacs, ~/.emacs.el, ~/.emacs.d/init.el, ~/.config/emacs/init.el; user-init-file tells you which.
  • early-init.el runs before the first frame and the package system, so keep it short.
  • Customize (M-x customize) writes custom-set-variables blocks; point custom-file elsewhere to keep init.el clean.
  • emacs -Q and --debug-init are the first tools for a broken configuration.
  • Keep the configuration under version control.

Next: Emacs Lisp Expressions and Data