49.4.4 How Emacs Finds Your Init File
Emacs normally finds your init file in a location under your home directory. See The Emacs Initialization 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.