Where apps hide your files

Finding your Emacs init file

Updated 2026-10-28 · 6 min read

Emacs checks four places for your init file, and on a Mac the winner is usually ~/.emacs.d/init.el. Here is the order, how to ask Emacs which one it loaded, and how to back it up.

The location

Emacs reads one init file at startup, and it looks in these places, in this order:

~/.emacs.el
~/.emacs
~/.emacs.d/init.el
~/.config/emacs/init.el

The first three are the classic spots. The fourth is the XDG-style location, which Emacs also supports. According to the GNU Emacs manual, ~/.emacs.d, ~/.emacs and ~/.emacs.el are always preferred when they exist, so the ~/.config/emacs folder is used only when none of those are present. If neither the XDG folder nor ~/.emacs.d exists, Emacs creates ~/.emacs.d itself and uses it from then on.

On a Mac the result is nearly always ~/.emacs.d/init.el, or a single ~/.emacs file in the home folder. All of these start with a dot, so Finder hides them. Press ⇧⌘. in a Finder window to show hidden files, or open the folder from Terminal:

open ~/.emacs.d

Ask Emacs which file it used

Guessing is unnecessary. Inside Emacs, type M-x describe-variable, press Return, then enter user-init-file. The help buffer shows the full path of the file Emacs loaded. Do the same with user-emacs-directory to see the folder where Emacs keeps everything else.

M-x means Meta and X. In Emacs.app (the Cocoa build), Emacs's own source sets Option as Meta and Command as Super by default. In Terminal, Option works as Meta only after you turn on Use Option as Meta key in Terminal's settings. Pressing Esc, then X, works everywhere.

If user-init-file shows nil, Emacs started without loading an init file, which is what emacs -q does.

The same config for every build of Emacs

All of the common ways to install Emacs on a Mac read the same files, because the config lives in your home folder and not in the app:

Install	Where the program is	Config
Emacs for Mac OS X (a direct download of Emacs.app)	/Applications/Emacs.app	~/.emacs.d or ~/.emacs
Homebrew cask emacs-app	/Applications/Emacs.app, plus an emacs command in Homebrew's bin folder	same
Homebrew formula emacs	under the Homebrew prefix: /opt/homebrew on Apple silicon, /usr/local on Intel	same

The Homebrew formula is built without the Cocoa interface (its build script passes --without-ns), so it is the terminal build. macOS itself no longer includes Emacs: there is no /usr/bin/emacs on the macOS 15 Mac used for this guide. Swapping one build for another does not touch your config, which is why upgrading Emacs rarely loses your settings.

The Cocoa app also keeps a small preferences file, ~/Library/Preferences/org.gnu.Emacs.plist, according to the Homebrew cask's own list of leftovers, along with a cache folder and saved window state. None of those hold your Emacs configuration.

What else lives in the folder

user-emacs-directory is where Emacs puts your other per-user files. The manual names the custom file, the saved desktop and the natively compiled Lisp cache. Beyond init.el, a typical folder can hold:

• early-init.el, read before the main init file and before the package system starts, in Emacs 27 and later. Most settings belong in init.el; the manual reserves this one for things that must happen first.
• elpa/, where the built-in package manager keeps packages you installed, one name-version folder each.
• eln-cache/, which holds natively compiled code, in builds that have native compilation.
• Files for features you turned on, such as saved places, bookmarks, recent files or a saved session. Their names depend on the packages you use, so list the folder to see what you have.

Settings you change through Customize are written as code, usually into your init file itself. The manual says you can redirect them by setting custom-file in the init file and loading it, which keeps your hand-written config free of generated lines.

Which one to use

If you are starting fresh, create ~/.emacs.d/init.el. Every current Emacs reads it, and it keeps packages, caches and config in one tidy folder. A lone ~/.emacs is fine for a short config. The XDG location is a good fit if you keep your dotfiles under ~/.config, with one catch: a leftover ~/.emacs.d folder wins over it, even an empty one. Rename or remove that folder to switch.

If you want the old path to keep working while the real files sit in ~/.config/emacs, the manual's own suggestion is a symbolic link:

ln -s ~/.config/emacs ~/.emacs.d

Run that only when ~/.emacs.d does not exist yet, or the link ends up inside the folder instead.

Back up before you edit

Quit Emacs first, because some packages write state files while running. Then copy, and only then edit. This leaves the originals alone:

cp -R ~/.emacs.d ~/emacs.d-backup

If your config is a single ~/.emacs file, copy that instead (cp ~/.emacs ~/emacs-backup.el). Start Emacs after editing and check that it loads without a warning buffer. To restore, quit Emacs and put the backup back under its old name. Packages in elpa/ can be reinstalled by the package manager, but copying the folder keeps the exact versions you had.

To try a change without risking your real setup, start a second Emacs with a different folder. Emacs 29 added the --init-directory option, which overrides user-emacs-directory. The manual adds a catch: if that folder has no init.el, Emacs falls back to the init file it would normally load, and ~/.emacs is still found either way. So create the test file first:

mkdir -p ~/emacs-test && touch ~/emacs-test/init.el
emacs --init-directory ~/emacs-test

If you used the direct-download app and emacs is not on your PATH, run the program inside the bundle instead: /Applications/Emacs.app/Contents/MacOS/Emacs. And emacs -q starts with no init file at all, which is the quickest test for whether your config is causing a problem.

Moving to a new Mac

Copy the init file and its folder, install Emacs, and start it once. The packages in elpa/ come along if you copy the whole folder, or are fetched again if your config lists them. Paths inside the config that point to your old username or to /usr/local (Intel Homebrew) rather than /opt/homebrew (Apple silicon) are the usual reason a copied config misbehaves.

Why a normal search misses it

.emacs.d and .emacs begin with a dot, and Finder searches skip hidden items. init.el is also named identically in thousands of other folders, which makes a bare name search noisy.

Finding it again

Typing init.el into Everywhere lists every copy on the Mac with its folder, so the one under .emacs.d or .config/emacs is easy to tell from a package's own init.el. Typing .emacs.d jumps to the folder itself, and ⌘T opens a Terminal there. Hidden dot-folders in your home folder are searched without extra setup. It matches file names only, not the Lisp inside them.

Common questions

Where is the Emacs config file on a Mac?

Most often ~/.emacs.d/init.el, or a single ~/.emacs file in your home folder. Emacs also supports ~/.config/emacs/init.el, but only when none of the older locations exist.

Should I use ~/.emacs.d or ~/.config/emacs?

Either works. The GNU Emacs manual says ~/.emacs.d, ~/.emacs and ~/.emacs.el are always preferred when they exist, so remove or rename them before the XDG folder is used.

How do I find which init file Emacs loaded?

Run M-x describe-variable, enter user-init-file, and read the path in the help buffer. user-emacs-directory shows the folder.

Does Homebrew Emacs use a different config from Emacs.app?

No. Both read your init file from your home folder, so switching builds keeps your settings.