49.4.4 How Emacs Finds Your Init File

Emacs normally finds your init file in a location under your home directory. See Init File.

Emacs looks for your init file using the filenames ~/.emacs.el, ~/.emacs, or ~/.emacs.d/init.el in that order; you can choose to use any one of these names. (Note that only the locations directly in your home directory have a leading dot in the location’s basename.)

Emacs can also look in an XDG-compatible location for init.el, the default is the directory ~/.config/emacs. This can be overridden by setting XDG_CONFIG_HOME in your environment, its value replaces ~/.config in the name of the default XDG init file. However ~/.emacs.d, ~/.emacs, and ~/.emacs.el are always preferred if they exist, which means that you must delete or rename them in order to use the XDG location.

Note also that if neither the XDG location nor ~/.emacs.d exist, then Emacs will create ~/.emacs.d (and therefore use it during subsequent invocations).

Emacs will set user-emacs-directory to the directory it decides to use.

Although this is backward-compatible with older Emacs versions, modern POSIX platforms prefer putting your initialization files under ~/.config so that troubleshooting a problem that might be due to a bad init file, or archiving a collection of init files, can be done by renaming that directory. To help older Emacs versions find configuration files in their current default locations, you can execute the following Emacs Lisp code:

(make-symbolic-link ".config/emacs" "~/.emacs.d")

However, if you run Emacs from a shell started by su and XDG_CONFIG_HOME is not set in your environment, Emacs tries to find your own initialization files, not that of the user you are currently pretending to be. The idea is that you should get your own editor customizations even if you are running as the super user.

More precisely, Emacs first determines which user’s init file to use. It gets your user name from the environment variables LOGNAME and USER; if neither of those exists, it uses the effective user-ID. If that user name matches the real user-ID, then Emacs uses HOME; otherwise, it looks up the home directory corresponding to that user name in the system’s data base of users.

For brevity the rest of the Emacs documentation generally uses just the current default location ~/.emacs.d/init.el for the init file.