49.4 The Emacs Initialization File

When Emacs is started, it normally tries to load a Lisp program from an initialization file, or init file for short. This file, if it exists, specifies how to initialize Emacs for you. Traditionally, file ~/.emacs is used as the init file, although Emacs also looks at ~/.emacs.el, ~/.emacs.d/init.el, ~/.config/emacs/init.el, or other locations. See Find Init.

You may find it convenient to have all your Emacs configuration in one directory, in which case you should use ~/.emacs.d/init.el or the XDG-compatible ~/.config/emacs/init.el.

You can use the command line switch ‘-q’ to prevent loading your init file, and ‘-u’ (or ‘--user’) to specify a different user’s init file (see Initial Options).

There can also be a default init file, which is the library named default.el, found via the standard search path for libraries. The Emacs distribution contains no such library; your site may create one for local customizations. If this library exists, it is loaded whenever you start Emacs (except when you specify ‘-q’). But your init file, if any, is loaded first; if it sets inhibit-default-init non-nil, then default is not loaded.

Your site may also have a site startup file; this is named site-start.el, if it exists. Like default.el, Emacs finds this file via the standard search path for Lisp libraries. Emacs loads this library before it loads your init file. To inhibit loading of this library, use the option ‘--no-site-file’. See Initial Options. We recommend against using site-start.el for changes that some users may not like. It is better to put them in default.el, so that users can more easily override them.

You can place default.el and site-start.el in any of the directories which Emacs searches for Lisp libraries. The variable load-path (see Lisp Libraries) specifies these directories. Many sites put these files in a subdirectory named site-lisp in the Emacs installation directory, such as /usr/local/share/emacs/site-lisp.

Byte-compiling your init file is not recommended (see Byte Compilation in the Emacs Lisp Reference Manual). It generally does not speed up startup very much, and often leads to problems when you forget to recompile the file. A better solution is to use the Emacs server to reduce the number of times you have to start Emacs (see Emacs Server). If your init file defines many functions, consider moving them to a separate (byte-compiled) file that you load in your init file.

If you are going to write actual Emacs Lisp programs that go beyond minor customization, you should read the Emacs Lisp Reference Manual. See Emacs Lisp in the Emacs Lisp Reference Manual.

• Init Syntax		Syntax of constants in Emacs Lisp.
• Init Examples		How to do some things with an init file.
• Terminal Init		Each terminal type can have an init file.
• Find Init		How Emacs finds the init file.
• Init Non-ASCII		Using non-ASCII characters in an init file.
• Early Init File		Another init file, which is read early on.