Frequently Asked Questions

General

Why is it called Doom?

It’s an homage to idsoftware’s classic game, whose source code was my first exposure to programming, back in the Cretaceous period (1999).

Also, Emacs is an all consuming black hole. Its users doom themselves, eternally.

Is Doom a fork of Spacemacs/Prelude/etc?

No. I started it from scratch in mid-2014. I hadn’t heard of other distros until some years later, when a Doom user suggested this was a Spacemacs fork. I still see this misconception pop up from time to time.

However, that’s not to say Doom hasn’t taken any inspiration from these since. Early versions of Doom drew inspiration from prelude’s project structure (until Doom introduced a module system) and some concepts (like SPC as a leader key) were adopted from Spacemacs or PRed from migrating users.

As our userbase grows, more similarities (and differences) will no doubt emerge.

Does Doom work on Windows?

It does, but there are caveats:

Emacs is inherently slower on Windows.
There are more steps to setting up Emacs (and Doom) on Windows.
Windows support will always lag behind macOS/Linux support, because I (and many of Doom’s users) don’t use Windows. That means fewer guinea p–I mean, pioneers, willing to test Doom on Windows.

That said, Doom does have happy Windows users (using WSL or scoop/chocolatey). The Getting Starting guide will walk you through what we know.

Help us improve our documentation if you managed to get Doom running on Windows!

Is Doom only for vimmers?

No, vim/evil emulation is optional. However, its maintainer is a dyed-in-the-wool vimmer with almost two decades of vim muscle memory, so the non-vim experience will be less polished. Still, our growing user base of non-vim users continue to improve the situation, and we welcome suggestions and contributions!

If you’d like a go at it, see the removing evil-mode section in the :editor evil module’s documentation.

I am a beginner. Can I use Doom?

This isn’t a choice I can make for you. How new is “new”? Are you new to the shell? To programming in general? Or just Emacs/vim?

If all of the above is true then Emacs is a rough place to start. Doom or not.

Emacs’ main draw is its unparalleled extensibility, but anything so extensible has a learning curve. Not to suggest it’s impossible – and we’ll try to help you if you ask – but expect a hefty commitment and a bumpy journey. Don’t pass up on the Documentation: it’ll work you through setting Doom up and includes links to external resources created by myself or the community.

How does Doom compare to Spacemacs?

To paraphrase (and expand upon) a reddit answer to this question by @gilbertw1:

Doom is lighter than Spacemacs. Doom starts up faster and is better optimized, but Spacemacs has more features.
Doom is thinner than Spacemacs. There are fewer abstractions between you and vanilla Emacs, and what abstractions do exist are thin by design. This means there’s less to understand and it’s easier to hack.
Doom is much more opinionated than Spacemacs. Doom does not strive to be a one-size-fits-all, beginner-friendly solution, nor is it configured by consensus. It is [mostly] the work of one developer and caters to his vim-slanted tastes. Doom’s defaults enforce very particular (albeit optional) workflows.
Doom lacks manpower. Bugs stick around longer, documentation is lighter and development is at the mercy of it’s maintainer’s schedule, health and whims.
Doom is not beginner friendly. Doom lacks a large community to constantly improve and produce tutorials/guides for it. Spacemacs is more likely to work right out of the box. Doom also holds your hand less. A little elisp, shell and git-fu will go a long way to ease you into Doom.
Doom is managed through it’s command line interface. The bin/doom script allows you to script package management, manage your config, or utilize elisp functionality externally, like org tangling or batch processing.
Doom’s package manager is declarative and rolling release is opt-in. Doom takes a little after nix, striving for as much config reproducibility as Emacs (and git) will permit. Spacemacs uses package.el, which is only rolling release.

Why such a complicated package management system?

Doom had ~~four~~ five goals for its package management system:

Scriptability: package management should be shell-scriptable, so updating can be automated.
Reach: allow users to install packages from sources other than ELPA (like github or gitlab), and from specific commits, branches or tags. Some plugins are out-of-date through official channels, have changed hands, have a superior fork, or aren’t available in ELPA repos.
Performance: lazy-loading the package management system is a tremendous boon to start up speed. Initializing package.el and straight (and/or checking that your packages are installed) or loading package autoloads files each time you start up is expensive.
Organization: an Emacs configuration grows so quickly, in complexity and size. A clear separation of concerns (configuration of packages from their installation) is easier to manage.
Reproducibility: Emacs is a tumultuous ecosystem; packages break left and right, and we rely on hundreds of them. By pinning our packages we achieve a degree of (optional) config reproducibility and significantly limit the damage upstream changes can do. Better yet, we stave off having to deal with those issues until we are ready to. Although technical limitations prevent us from achieving true reproducibility, this is better than nothing.

How does Doom start up so quickly?

Doom employs a number of techniques to cut down startup time. Here are its most effective techniques:

Avoid garbage collection at startup

The GC can easily double startup time, so we suppress it at startup by turning up gc-cons-threshold (and perhaps gc-cons-percentage) temporarily:

(setq gc-cons-threshold most-positive-fixnum ; 2^61 bytes
      gc-cons-percentage 0.6)

;; ... your emacs config here ...

However, it is important to reset it eventually. Not doing so will cause garbage collection freezes during long-term interactive use. Conversely, a gc-cons-threshold that is too small will cause stuttering. We use 16mb as our default.

(add-hook 'emacs-startup-hook
  (lambda ()
    (setq gc-cons-threshold 16777216 ; 16mb
          gc-cons-percentage 0.1)))

It may also be wise to raise gc-cons-threshold while the minibuffer is active, so the GC doesn’t slow down expensive commands (or completion frameworks, like helm and ivy). Here is how Doom does it:

(defun doom-defer-garbage-collection-h ()
  (setq gc-cons-threshold most-positive-fixnum))

(defun doom-restore-garbage-collection-h ()
  ;; Defer it so that commands launched immediately after will enjoy the
  ;; benefits.
  (run-at-time
   1 nil (lambda () (setq gc-cons-threshold doom-gc-cons-threshold))))

(add-hook 'minibuffer-setup-hook #'doom-defer-garbage-collection-h)
(add-hook 'minibuffer-exit-hook #'doom-restore-garbage-collection-h)

Another alternative (which is what Doom uses) is the gcmh package; which staves off the GC until you are idle. Doom also triggers GC when you unfocus the Emacs frame.

Concatenate package autoloads

When you install a package, a PACKAGE-autoloads.el file is generated. This file maps autoloaded functions and snippets to their containing package so Emacs will know where to find them when they are used. In your conventional Emacs config, every one of these autoloads files are loaded immediately at startup (when package-initialize is called).

Since you’ll commonly have hundreds of packages, loading hundreds of autoloads file can hurt startup times, especially without an SSD. We get around this by concatenating these files into one giant one when you run doom sync.

Emacs 27+ introduces a package-quickstart command that does this for you, and straight (which powers our package manager) does this for you too, but Doom Emacs has its own specialized mechanism for this, topped off with a few Doom-specific optimizations.

Lazy load package management system(s)

Initializing package.el or straight.el at startup is expensive. We can save some time by delaying that initialization until we actually need these libraries (and load them only when we’re doing package management, e.g. when we run doom sync).

Among other things, doom sync does a lot for us. It generates concatenated autoloads files; caches expensive variables like caches load-path, Info-directory-list and auto-mode-alist; and preforms all your package management activities there – far away from your interactive sessions.

How exactly Doom accomplishes all this is a long story, so here is a boiled-down version you can use in your own configs (for package.el, not straight.el):

(defvar cache-file "~/.emacs.d/cache/autoloads")

(defun initialize ()
  (unless (load cache-file t t)
    (setq package-activated-list nil)
    (package-initialize)
    (with-temp-buffer
      (cl-pushnew doom-core-dir load-path :test #'string=)
      (dolist (desc (delq nil (mapcar #'cdr package-alist)))
        (let ((load-file-name (concat (package--autoloads-file-name desc) ".el")))
          (when (file-readable-p load-file-name)
            (condition-case _
                (while t (insert (read (current-buffer))))
              (end-of-file)))))
      (prin1 `(setq load-path ',load-path
                    auto-mode-alist ',auto-mode-alist
                    Info-directory-list ',Info-directory-list)
             (current-buffer))
      (write-file (concat cache-file ".el"))
      (byte-compile-file cache-file))))

(initialize)

You’ll need to delete cache-files any time you install, remove, or update a new package. You could advise package-install and package-delete to call initialize when they succeed, or make initialize interactive and call it manually when necessary. Up to you!

Note: package.el is sneaky, and will initialize itself if you’re not careful. Not on my watch, criminal scum!

;; in ~/.emacs.d/init.el (or ~/.emacs.d/early-init.el in Emacs 27)
(setq package-enable-at-startup nil ; don't auto-initialize!
      ;; don't add that `custom-set-variables' block to my init.el!
      package--init-file-ensured t)

Lazy load more than everything

use-package can defer your packages. Using it is a no-brainer, but Doom goes a step further. There are some massive plugins out there for which ordinary lazy loading techniques don’t work. To name a few:

The lang/org module defers loading babel packages until their src blocks are executed or read. You no longer need org-babel-do-load-languages in your config – in fact, you shouldn’t use it at all!
org-protocol needs to be loaded to intercept requests for org-protocol:// URLs. Since org-protocol depends on org, this can be expensive to load yourself, so Doom loads as soon as a org-protocol:// request is received, just before it is processed.
Company and yasnippet are loaded as late as possible (waiting until the user opens a non-read-only, file-visiting buffer (that isn’t in fundamental-mode)).
The evil-easymotion package binds many keys, none of which are available until you load the package. Instead of loading it at startup, gs is bound to a command that loads the package, populates gs, then simulates the gs key press as though those new keys had always been there.

In addition, Doom loads some packages “incrementally”. i.e. after a few seconds of idle time post-startup, Doom loads packages piecemeal (one dependency at a time) while Emacs. It aborts if it detects input, as to make the process as subtle as possible.

For example, instead of loading org (a giant package), it will load these dependencies, one at a time, before finally loading org:

(calendar find-func format-spec org-macs org-compat org-faces
 org-entities org-list org-pcomplete org-src org-footnote
 org-macro ob org org-agenda org-capture)

This ensures packages load as quickly as possible when you first load an org file.

Unset `file-name-handler-alist` temporarily

Emacs consults this variable every time a file is read or library loaded, or when certain functions in the file API are used (like expand-file-name or file-truename).

Emacs does to check if a special handler is needed to read that file, but none of them are (typically) necessary at startup, so we disable them (temporarily!):

(defvar doom--file-name-handler-alist file-name-handler-alist)
(setq file-name-handler-alist nil)

;; ... your whole emacs config here ...

;; Then restore it later:
(setq file-name-handler-alist doom--file-name-handler-alist)

;; Alternatively, restore it even later:
(add-hook 'emacs-startup-hook
  (lambda ()
    (setq file-name-handler-alist doom--file-name-handler-alist)))

Don’t forget to restore file-name-handler-alist, otherwise TRAMP won’t work and compressed/encrypted files won’t open.

Use lexical-binding everywhere

Add ;; -*- lexical-binding: t; -*- to the top of your elisp files. This can break code if you’ve written it to depend on undeclared dynamic variables, but I’ve designed Doom not to.

This buys a small improvement in performance, but every little bit helps. You’ll find more about it in:

“How to Write Fast(er) Emacs Lisp.”
“Some Performance Advantages of Lexical Scope.”

Why is startup time important? Why not use the daemon?

It isn’t terribly important, but I believe a) faster software is a better user experience, b) Emacs doesn’t have to be slower than it needs to be, and c) we shouldn’t have to manage yet-another-tool simply to get sane startup times out of Emacs.

A fast startup time also facilitates:

Emacs as a viable alternative to vim for quick, one-shot editing in the terminal (without -Q).
Running multiple, independent instances of Emacs (e.g. on a per-project basis, or for nix-shell users, or to isolate one instance for IRC from an instance for writing code, etc).
Quicker restarting of Emacs, to reload package settings or recover from disastrous errors which can leave Emacs in a broken state.
Faster integration with “edit in Emacs” solutions (like atomic-chrome), and without a daemon.

It’s up to you to decide if these are good enough reasons not to use a daemon, but it’s nice to have more options, isn’t it?

How do I use Doom alongside other Emacs configs?

I recommend Chemacs. Think of it as a bootloader for Emacs. You’ll find instructions on how to use it with Doom in the user manual.

You will need a separate folder for personal configuration (~/.doom.d or ~/.config/doom by default). Use the DOOMDIR environment variable to use another location:

# First install Doom somewhere
git clone https://github.com/hlissner/doom-emacs ~/fakehome/doom-emacs
# Then create a place to store our private doom configs. The bin/doom script
# recognizes the DOOMDIR environment variable.
export DOOMDIR=~/fakehome/doom-emacs-config
mkdir -p "$DOOMDIR"

# Set up Doom for the first time; this may take a while
cd ~/fakehome/doom-emacs
bin/doom install

# then launch Doom Emacs from this folder with:
bin/doom run

Warning: the way bin/doom run starts Doom bypasses many of its startup optimizations. Treat it as a convenience for testing rather than a permanent entry point.

Why should I use Doom instead of rolling my own config?

Two reasons:

Doom’s package manager. It’s powered by straight.el, is declarative, non-rolling release and (nominally) reproducible; which is unique on the Emacs distro scene. Don’t let upstream issues surprise you. Roll back or re-pin packages when you don’t have the time to deal with issues.
It also integrates with command line workflows, so automate to your heart’s content!
Time. If you care about personalizing the software you use on a daily basis, even half as much as I do, then you need professional help, but you also know it is time consuming. Emacs out-of-the-box is a wasteland of archaic defaults, full of plugins rife with gotchas and oddities that may or may not be abandonware. It will be an uphill battle. Let Doom deal with all that noise. Save yourself some time.
Time you could otherwise spend attending your daughter’s dance recitals, that baseball game your son’s team almost won last Thursday, or answering the court summons to fight for custody of your kids.

Also, Doom’s fast yo.

What is the meaning behind Doom’s naming convention in its source code?

You’ll find an overview of Doom’s code conventions in the contributing guide.

What version of Doom am I running?

The current version of Doom is displayed in the modeline on the dashboard. It can also be retrieved using M-x doom/version (bound to SPC h d v or C-h d v by default) or bin/doom version on the command line.

Is Discord the only option for interacting with your community?

Yes. Discord is already woven into my social and work life, and was selected to maximize my availability to the community. I don’t want to juggle multiple platforms (like Matrix, IRC or Slack), or add bridges for them, even if they are better suited to the task. I already have my hands full managing the one.

I am considering a discourse, so we have a public knowledge base of workflows and inter-user support (since Discord isn’t a great archive), but it will be some time until this is set up.

Email is a possible alternative, but is constantly swamped; expect a turn-around time of weeks.

Why is Emacs/Doom slow?

This comes up often. The first thing folks fresh off the boat from other editors will notice is that Emacs has a low threshold for performance issues. It doesn’t take much to get it to scroll like molasses.

Retina/4K/high res users have it especially hard. MacOS users too, where Emacs seem even slower. Add to that files that are large (perhaps 1mb+) or have long lines (200 characters+) and we’ve got ourselves a really poor experience. And that’s before we factor in plugins and poorly optimized major modes.

There is an unfortunate but necessary adjustment of expectations new users must undergo, when they adopt Emacs. Doom has inherited this curse. Its raison d’etre is to improve the situation, but I can only go so far, especially if you choose to enable all the most expensive features. You will unavoidably find cases where Emacs is just slow.

What can you do about it?

Upgrade to Emacs 27. This should yield a noteworthy gain in general performance, particularly for LSP users.
Try out gccemacs, which promises significant strides in Emacs performance, but can be a bit of a hassle to set up. There are packages available for Arch Linux, Guix and Nix users. More information available on EmacsWiki.
Disable some of Doom’s slowest modules. The biggest offenders tend to be: :ui tabs, :ui indent-guides, :ui ligatures, :editor word-wrap and :ui vc-gutter.
Turn off line numbers (setq display-line-numbers-type nil). It’s known to slow down scrolling, in particular.
Org users can turn off org-superstar-mode: (remove-hook 'org-mode-hook #'org-superstar-mode). It’s an aesthetic plugin that offers fancier bullets. Emacs seems to struggle to display those characters with some fonts.
Org uses can also turn off the rest of org’s eye candy:
```
(after! org
  (setq org-fontify-quote-and-verse-blocks nil
        org-fontify-whole-heading-line nil
        org-hide-leading-stars nil
        org-startup-indented nil))
    
```
Turn on M-x so-long-minor-mode. This is a minor mode that disables non-essential functionality and can be used to temporarily view files that would be too slow otherwise. M-x so-long-mode is its extreme version; it turns off everything, including syntax highlighting.
Try replacing the :ui modeline module with :ui (modeline +light). There are aspects of the default modeline that can be unpredictably slow.
Don’t mash j (or C-n) to scroll. Evil users can scroll long distances with C-d and C-u, for instance, or evil-easymotion under gs, to avoid that slowness. Otherwise, use search mechanisms to move around, like isearch (C-s) or evil-search (/).

Configuration

How do I configure Doom Emacs?

Canonically, your private config is kept in ~/.doom.d/ (or ~/.config/doom/). This directory is referred to as your $DOOMDIR.

Your private config is typically comprised of an init.el, config.el and packages.el file. Put all your config in config.el, install packages by adding package! declarations to packages.el, and enable/disable modules in you doom! block, which should have been created in your init.el when you first ran doom install.

You shouldn’t need to fork Doom or modify ~/.emacs.d. If you have to do this to achieve something, it can be considered a bug.

Check out the Customize section in the Getting Started guide for details.

Does Doom respect XDG directory conventions

Yes. Your private config (normally in ~/.doom.d) can be moved to ~/.config/doom.

And as of Emacs 27, ~/.emacs.d can be moved to ~/.config/emacs.

How do I enable or disable a Doom module?

Comment or uncomment the module in your doom! block, found in ~/.doom.d/init.el.

Remember to run bin/doom sync afterwards, on the command line, to sync your module list with Doom.

See the ”Configuration modules” section of the Getting Started guide for more information.

How do I change the theme?

There are two ways to load a theme. Both assume the theme is installed and available. You can either set doom-theme or manually load a theme with the load-theme function.

;;; add to ~/.doom.d/config.el
(setq doom-theme 'doom-tomorrow-night)
;; or
(load-theme 'doom-tomorrow-night t)

At the moment, the only difference between the two is that doom-theme is loaded when Emacs has finished initializing at startup and load-theme loads the theme immediately. Which you choose depends on your needs, but I recommend setting doom-theme because, if I later discover a better way to load themes, I can easily change how Doom uses doom-theme, but I can’t (easily) control how you use the load-theme function.

Installing a third party theme

To install a theme from a third party plugin, say, solarized, you need only install it, then load it:

;;; add to ~/.doom.d/packages.el
(package! solarized-theme)

;;; add to ~/.doom.d/config.el
(setq doom-theme 'solarized-dark)

Don’t forget to run doom sync after adding that package! statement to ensure the package is installed.

How do I change the fonts?

Doom exposes five (optional) variables for controlling fonts in Doom, they are:

doom-font
doom-variable-pitch-font
doom-serif-font
doom-unicode-font (the fallback font for unicode symbols that your default font doesn’t support)
doom-big-font (used for doom-big-font-mode)

They all accept either a font-spec, font string ("Input Mono-12"), or xlfd font string.

e.g.

;;; Add to ~/.doom.d/config.el
(setq doom-font (font-spec :family "Input Mono Narrow" :size 12 :weight 'semi-light)
      doom-variable-pitch-font (font-spec :family "Fira Sans") ; inherits `doom-font''s :size
      doom-unicode-font (font-spec :family "Input Mono Narrow" :size 12)
      doom-big-font (font-spec :family "Fira Mono" :size 19))

How do I bind my own keys (or change existing ones)?

There are many options. Emacs provides a number of keybind functions:

define-key KEYMAP KEY DEF
global-set-key KEY DEF
local-set-key KEY DEF
evil-define-key STATES KEYMAP KEY DEF &rest ...

However, Doom provides a map! macro, which conveniently wraps up the above four into a more succinct syntax. Comprehensive examples of map!’s usage can be found in its documentation (via SPC h f map\! or C-h f map\! – or in docs/api).

There are also live examples map!’s usage in config/default/+evil-bindings.el.

How do I get motions to treat underscores as word delimiters?

(This explanation comes from emacs-evil/evil’s readme)

An underscore “_” is a word character in Vim. This means that word-motions like w skip over underlines in a sequence of letters as if it was a letter itself. In contrast, in Evil the underscore is often a non-word character like operators, e.g. +.

The reason is that Evil uses Emacs’ definition of a word and this definition does not often include the underscore. Word characters in Emacs are determined by the syntax-class of the buffer. The syntax-class usually depends on the major-mode of this buffer. This has the advantage that the definition of a “word” may be adapted to the particular type of document being edited. Evil uses Emacs’ definition and does not simply use Vim’s definition in order to be consistent with other Emacs functions. For example, word characters are exactly those characters that are matched by the regular expression character class [:word:].

If you want the underscore to be recognized as word character, you can modify its entry in the syntax-table:

(modify-syntax-entry ?_ "w")

This gives the underscore the word syntax-class. You can use a mode-hook to modify the syntax-table in all buffers of some mode, e.g.:

;; For python
(add-hook! 'python-mode-hook (modify-syntax-entry ?_ "w"))
;; For ruby
(add-hook! 'ruby-mode-hook (modify-syntax-entry ?_ "w"))
;; For Javascript
(add-hook! 'js2-mode-hook (modify-syntax-entry ?_ "w"))

How do I change the leader/localleader keys?

These variables control what key to use for leader and localleader keys:

For Evil users:
- doom-leader-key (default: SPC)
- doom-localleader-key (default: SPC m)
For Emacs and Insert state (evil users), and non-evil users:
- doom-leader-alt-key (default: M-SPC for evil users, C-c otherwise)
- doom-localleader-alt-key (default: M-SPC m for evil users, C-c l otherwise)

e.g.

;;; add to ~/.doom.d/config.el
(setq doom-leader-key ","
      doom-localleader-key "\\")

How do I change the style of line-numbers (or disable them altogether)?

Doom uses the display-line-numbers package, which is built into Emacs 26+.

Disabling line numbers entirely

;;; add to ~/.doom.d/config.el
(setq display-line-numbers-type nil)
;; or
(remove-hook! '(prog-mode-hook text-mode-hook conf-mode-hook)
              #'display-line-numbers-mode)

Switching to relative line numbers (permanently)

To change the style of line numbers, change the value of the display-line-numbers-type variable. It accepts the following values:

t            normal line numbers
'relative    relative line numbers
'visual      relative line numbers in screen space
nil          no line numbers

For example:

;;; add to ~/.doom.d/config.el
(setq display-line-numbers-type 'relative)

You’ll find more precise documentation on the variable through <help> v display-line-numbers-type (<help> is SPC h for evil users, C-h otherwise).

Switching the style of line numbers (temporarily)

Use M-x doom/toggle-line-numbers (bound to SPC t l by default) to cycle through the available line number styles in the current buffer.

e.g. normal -> relative -> visual -> disabled -> normal.

How do I change the behavior and appearance of popup windows?

The :ui popup module tries to standardize how Emacs handles “temporary” windows. It includes a set of default rules that tell Emacs where to open them (and how big they should be).

Check out the :ui popup module’s documentation for more on defining your own rules.

You’ll find more comprehensive documentation on set-popup-rule! in its docstring (available through SPC h f – or C-h f for non-evil users).

How do I customize a theme or face(s)?

Doom provides the custom-set-faces! and custom-theme-set-faces! macros as a convenience.

See SPC h f custom-set-faces\! (or C-h f custom-set-faces\!) for documentation on and examples of its use.

Other sources may recommend M-x customize, M-x customize-themes or M-x customize-face. Do not use these commands. Doom does not support them and their settings could break any time.

How do I make a new theme?

Doom will look for themes in ~/.doom.d/themes/ (determined by custom-theme-directory).

Its filename must take the format XYZ-theme.el, where XYZ is the theme’s name declared in that theme’s deftheme or def-doom-theme call. The theme can then be loaded with:

;; add to ~/.doom.d/config.el
(setq doom-theme 'XYZ)

;; or

(load-theme 'XYZ t)

Can Doom be customized without restarting Emacs?

Short answer: You can, but you shouldn’t.

Long answer: Restarting Emacs is always your safest bet, but Doom provides a few tools for experienced Emacs users to skirt around it (most of the time):

Evaluate your changes on-the-fly with +eval/region (bound to the gr operator for evil users) or eval-last-sexp (bound to C-x C-e). Changes take effect immediately.
On-the-fly evaluation won’t work for all changes. e.g. Changing your doom! block (i.e. the list of modules for Doom to enable).
But rather than running doom sync and restarting Emacs, Doom provides M-x doom/reload for your convenience (bound to SPC h r r and C-h r r). This runs doom sync, restarts the Doom initialization process and re-evaluates your personal config. However, this won’t clear pre-existing state; Doom won’t unload modules/packages that have already been loaded and it can’t anticipate complications arising from your private config.
You can quickly restart Emacs and restore the last session with doom/restart-and-restore (bound to SPC q r).

Can Vim/Evil be removed for a more vanilla Emacs experience?

Yes! See the Removing evil-mode section in :editor evil’s documentation.

When should and shouldn’t I use `bin/doom`?

bin/doom is your best friend. It’ll keep all your secrets (mostly because it’s a shell script incapable of sentience and thus incapable of retaining, much less divulging, your secrets to others).

You can run bin/doom help to see what it’s capable of, but here are some commands that you may find particularly useful:

doom doctor

Diagnose common issues in your environment and list missing external dependencies for your enabled modules.

doom sync

Ensures that all missing packages are installed, orphaned packages are removed, and metadata properly generated.

doom install

Install any missing packages.

doom update

Update all packages that Doom’s (enabled) modules use.

doom env

Regenerates your envvar file, which contains a snapshot of your shell environment for Doom Emacs to load on startup. You need to run this for changes to your shell environment to take effect.

doom purge -g

Purge orphaned packages (i.e. ones that aren’t needed anymore) and regraft your repos.

doom upgrade

Upgrade Doom to the latest version (then update your packages). This is equivalent to:

git pull
doom sync
doom update

When to run `doom sync`

As a rule of thumb you should run doom sync whenever you:

Update Doom with git pull instead of doom upgrade,
Change your doom! block in $DOOMDIR/init.el,
Change autoload files in any module (or $DOOMDIR),
Or change the packages.el file in any module (or $DOOMDIR).
Install an Emacs package or dependency outside of Emacs (i.e. through your OS package manager).

If anything is misbehaving, it’s a good idea to run doom sync first. doom sync is responsible for regenerating your autoloads file (which tells Doom where to find lazy-loaded functions and libraries), installing missing packages, and uninstall orphaned (unneeded) packages.

How to suppress confirmation prompts while `bin/doom` is running

The -y and --yes flags (or the YES environment variable) will force bin/doom to auto-accept confirmation prompts:

doom -y update
doom --yes update
YES=1 doom update

Which terminal should I use?

Looking for a terminal in Emacs? Doom offers four modules:

:term eshell
:term shell,
:term term
:term vterm.

But which do you choose?

eshell is a shell completely implemented in Emacs Lisp. It’s stable, works anywhere Emacs runs (on any OS) and has no external dependencies, but lacks features you’ll expect from mature shells, tends to be slower than them, and does not support command line tools with TUIs (e.g. curses, ncdu, nmtui, top, etc).
shell is a shell for your shell. Think of it like a REPL for bash/zsh, rather than a terminal emulator. Due to its simplicity, you’re less likely to encounter edge cases (e.g. against your shell config), but it has the smallest feature set. It also won’t work with TUI programs like htop or vim.
term is Emacs’ built-in terminal emulator. Term runs a shell and understand many (but not all) terminal escape codes, so many TUI programs (like top or vim) will work. However, term’s performance is inferior to standalone terminals, especially with large bursts of output.
vterm is as good as terminal emulation gets in Emacs (at the time of writing), and is the most performant, as it is an external library written in C. However, it requires extra steps to set up. a) Emacs must be built with dynamic modules support and b) you’ll need to compile vterm-module.so, which has external dependencies (libvterm). It is automatically built when you first open vterm, but this will fail on Windows, NixOS and Guix out of the box. Except for Windows, you’ll find install instructions for nix/guix in the :term vterm module’s documentation.

For a terminal in Emacs, eshell and vterm are generally the best options.

How do I enable LSP support for <insert language here>?

Doom supports LSP, but it is not enabled by default. To enable it, you must:

Enable the :tools lsp module,
Enable the +lsp flag for the appropriate modules you want LSP support for (e.g. :lang (python +lsp) or :lang (rust +lsp)),
Install the prerequisite LSP servers through your package manager or other means. You can find a list of supported servers on the lsp-mode project page.
Run doom sync on the command line and restart Emacs.

Some language modules may lack LSP support (either because it hasn’t been implemented yet or I’m not aware of it yet – let us know!). To enable LSP for these languages, add this to $DOOMDIR/config.el:

(add-hook 'MAJOR-MODE-local-vars-hook #'lsp!)
;; Where =MAJOR-MODE= is the major mode you're targeting. e.g.
;; lisp-mode-local-vars-hook

How to disable smartparens/automatic parentheses completion?

Some outdated sources may tell you to do this, but it is no longer correct:

(after! smartparens
  (smartparens-global-mode -1))

Instead, use the following:

(remove-hook 'doom-first-buffer-hook #'smartparens-global-mode)

Note that the package itself cannot be disabled with package!, because it is a core package. This may change one day, but not in the near future.

How do I maximize/fullscreen Emacs on startup?

(add-to-list 'initial-frame-alist '(fullscreen . maximized))

Some window managers may not understand/work with maximized (or may not produce the desired effect), in that case try fullboth or fullscreen.

How do I share/sync my config between multiple computers?

TL;DR: it is perfectly safe to sync ~/.doom.d, but not ~/.emacs.d.

Long answer: ~/.emacs.d/.local can contain baked-in absolute paths and non-portable byte-code. It is never a good idea to sync it across multiple computers.

If you must, for some reason, copy ~/.emacs.d from one system to another, remember to run doom sync && doom build on the target machine.

Package Management

How do I install a package from ELPA?

See the ”Installing packages” section of the Getting Started guide.

How do I install a package from github/another source?

See the ”Installing packages from external sources” section of the Getting Started guide.

How do I change where an existing package is installed from?

See the ”Changing a recipe for a included package” section of the Getting Started guide.

How do I disable a package completely?

See the ”disabling packages” section of the Getting Started guide.

How do I reconfigure a package included in Doom?

See the ”configuring packages” section of the Getting Started guide.

Where does straight clone/build packages to?

Doom has configured straight to clone packages to ~/.emacs.d/.local/straight/repos/REPO-NAME. It then builds (byte-compiles and symlinks) them to ~/.emacs.d/.local/straight/build/PACKAGE-NAME.

Defaults

Why Ivy over Helm?

Short answer: ivy is simpler to maintain.

Long answer: Features and performance appear to be the main talking points when comparing the two, but as far as I’m concerned they are equal in both respects (not all across the board, but on average).

Instead, maintainability is most important for someone that frequently tinkers with their editor. When I have an issue, I spend disproportionately more time dealing helm than I do ivy, for little or no gain. Though both frameworks are excellent, the difference in complexity is reflected in their plugin ecosystems; ivy plugins tend to be lighter, simpler, more consistent and significantly easier to hack if I want to change something. Unless you like helm just the way it is out of the box, ivy is just the simpler choice.

And since I dogfood it, Ivy’s integration into Doom will always be a step or three ahead of helm’s.

Why are there no default keybinds for Smartparens (for evil users)?

Doom only uses smartparens to manage pair “completion” (it does the job better than electric-{pair,quote}-mode or the multitude of other pair-management solutions in the Emacs ecosystem at the time of writing).

None of smartparen’s commands have default keybinds for evil users because they are redundant with motions and text-objects provided by evil/vim. If you disagree, I recommend trying the :editor lispy or :editor parinfer modules.

Why do non-evil users get expand-region, but not evil users?

expand-region is redundant with and less precise than evil’s text objects and motions.

There’s a text object for every “step” of expansion that expand-region provides (and more). To select the word at point = viw, symbol at point = vio, line at point = V, the block at point (by indentation) = vii, the block at point (by braces) = vib, sentence at point = vis, paragraph = vip, and so on.
Selection expansion can be emulated by using text objects consecutively: viw to select a word, followed by io to expand to a symbol, then ib expands to the surrounding brackets/parentheses, etc. There is no reverse of this however; you’d have to restart visual state.

The expand-region way dictates you start at some point and expand/contract until you have what you want selected. The vim/evil way would rather you select exactly what you want from the get go. In the rare event a text object fails you, a combination of o (swaps your cursor between the two ends of the region) and motion keys can adjust the ends of your selection.

There are also text objects for xml tags (x), C-style function arguments (a), angle brackets, and single/double quotes.

This is certainly more to remember compared to a pair of expand and contract commands, but text objects (and motions) are the bread and butter of vim’s modal editing paradigm. Vimmers will feel right at home. To everyone else: mastering them will have a far-reaching effect on your productivity. I highly recommend putting in the time to learn them.

Otherwise, it is trivial to install expand-region and binds keys to it yourself:

;;; add to ~/.doom.d/packages.el
(package! expand-region)

;;; add to ~/.doom.d/config.el
(map! :nv "C-=" #'er/contract-region
      :nv "C-+" #'er/expand-region)

Why not use exec-path-from-shell instead of `doom env`?

The doom env approach is a faster and more reliable solution.

exec-path-from-shell must spawn (at least) one process at startup to scrape your shell environment. This can be slow depending on the user’s shell configuration. A single program (like pyenv or nvm) or config framework (like oh-my-zsh) could undo Doom’s startup optimizations in one fell swoop.
exec-path-from-shell takes a whitelist approach and captures only PATH and MANPATH by default. You must be proactive in order to capture all the envvars relevant to your development environment and tools.

doom env takes the blacklist approach and captures all of your shell environment. This front loads the debugging process, which is nicer than dealing with it later, while you’re getting work done.

That said, if you still want exec-path-from-shell, it is trivial to install yourself:

;;; add to ~/.doom.d/packages.el
(package! exec-path-from-shell)

;;; add to ~/.doom.d/config.el
(require 'exec-path-from-shell)
(when (display-graphic-p)
  (exec-path-from-shell-initialize))

Why wsbutler over delete-trailing-whitespace or whitespace-cleanup?

TL;DR: ws-butler is less imposing.

Don’t be that guy who PRs 99 whitespace adjustments around his one-line contribution. Don’t automate this aggressive behavior by attaching delete-trailing-whitespace (or whitespace-cleanup) to before-save-hook. If you have rambunctious colleagues peppering trailing whitespace into your project, you need to have a talk (with wiffle bats, preferably) rather than play a passive-aggressive game of whack-a-mole.

Here at Doom Inc we believe that operations that mutate entire files (or worse, projects) should not be automated. Rather, they should be invoked deliberately, only when and where it is needed, by someone that is aware of the consequences. This is where ws-butler comes in. It only cleans up whitespace on the lines you’ve touched and it leaves behind virtual whitespace (which is never written to the file) so your cursor doesn’t get thrown around in all that cleanup work.

In any case, if you had used ws-butler from the beginning, trailing whitespace and newlines would never be a problem!

Emacs Lisp

Why do you quote some symbols with `#'symbol`?

#'symbol is short for (function symbol), the same way 'symbol is short for (quote symbol).

In elisp there is no functional difference between the two syntaxes, but the sharp-quote does hint to the byte-compiler that “this symbol refers to a function”, which it can perform additional checks on when the code is byte-compiled.

My reason for using it is to make it explicit to readers how I intend (or expect) the symbol to be used. No sharp-quote means I’m using the symbol as a literal data value.

Common Issues

I get the vanilla Emacs splash screen at startup

The most common cause for this is a ~/.emacs file. If it exists, Emacs will read this file instead of the ~/.emacs.d directory, ignoring Doom altogether.

If this isn’t the case, try running bin/doom doctor. It can detect a variety of common issues and may give you some clues as to what is wrong.

I see a blank scratch buffer at startup

This commonly means that Emacs can’t find your private doom config (in ~/.doom.d or ~/.config/doom). Make sure only one of these two folders exist, and that it has an init.el file with a doom! block. Running doom install will populate your private doom directory with the bare minimum you need to get going.

If nothing else works, try running bin/doom doctor. It can detect a variety of common issues and may give you some clues as to what is wrong.

Strange (or incorrect) icons are displayed everywhere

Many of Doom’s UI modules use the all-the-icons plugin, which uses special fonts to display icons. These fonts must be installed for them to work properly, otherwise you’ll get a bunch of squares and mismatched icons. When running doom install, you will be asked whether you want these installed for you or not.

If you did not accept or need to reinstall those fonts, MacOS and Linux users can install them with M-x all-the-icons-install-fonts. Windows users will need to use this command to download the fonts somewhere, then they must install them manually (e.g. by double-clicking each file in explorer).

`void-variable` and `void-function` errors on startup

The most common culprit for these types of errors are:

An out-of-date autoloads file. Run doom sync to regenerate them.
To avoid this issue, remember to run doom sync whenever you modify your doom! block in ~/.doom.d/init.el, or add package! declarations to ~/.doom.d/packages.el. Or if you modify ~/.emacs.d/.local by hand, for whatever reason.

See doom help sync for details on what this command does and when you should use it.
Emacs byte-code isn’t forward compatible. If you’ve recently switched to a newer (or older) version of Emacs, you’ll need to either reinstall or recompile your installed plugins. This can be done by:
- Running doom build,
- Or deleting ~/.emacs.d/.local/straight then running doom install (this will take a while).

Doom can’t find my executables/doesn’t inherit the correct `PATH`

The two most common causes for PATH issues in Doom are:

Your shell configuration doesn’t configure PATH correctly. If which <PROGRAM> doesn’t emit the path you expect on the command line then this is likely the case.
Your app launcher (rofi, albert, docky, dmenu, sxhkd, etc) is launching Emacs with the wrong shell, either because it defaults to a different shell from the one you use or the app launcher itself inherits the wrong environment because it was launched from the wrong shell.
You’re a Mac user launching Emacs from an Emacs.app bundle. MacOS launches these apps from an isolated environment.

As long as your shell is properly configured, there is a simple solution to issues #1 and #3: generate an envvar file by running doom env. This scrapes your shell environment into a file that is loaded when Doom Emacs starts up. Check out doom help env for details on how this works.

For issue #2, you’ll need to investigate your launcher. Our Discord is a good place to ask about it.

There’s artefacting on my icon fonts in GUI Emacs (#956)

Check your font rendering settings. Changing the RGBA order to “rgba” will often fix this issue. See #956 for details.

The `s` and `S` keys don’t behave like they do in vim/evil (#1307)

This is intentional. s and S have been replaced by the evil-snipe plugin, which provides 2-character versions of the f/F motion keys, ala vim-seek or vim-sneak.

These keys were changed because they are redundant with cl and cc respectively (and the new behavior was deemed more useful).

If you still want to restore the old behavior, simply disable evil-snipe-mode:

;; in ~/.doom.d/config.el
(after! evil-snipe
  (evil-snipe-mode -1))

Changes to my config aren’t taking effect

Make sure you don’t have both ~/.doom.d and ~/.config/doom directories. Doom will ignore the former if the latter exists.
Remember to run doom sync when it is necessary. To get to know when, exactly, you should run this command, run doom help sync.

If neither of these solve your issue, try bin/doom doctor. It will detect a variety of common issues, and may give you some clues as to what is wrong.

The frame goes black on MacOS, while in full-screen mode

There are known issues with childframes and macOS’s fullscreen mode. There is no known fix for this. To work around it, you must either:

Avoid MacOS native fullscreen by maximizing Emacs instead,
Disable childframes (controlled by the +childframe flag on the modules that support it),
Install Emacs via the emacs-mac homebrew formula.

Doom crashes when…

Here are a few common causes for random crashes:

On some systems (particularly MacOS), manipulating the fringes or window margins can cause Emacs to crash. This is most prominent in the Doom Dashboard (which tries to center its contents), in org-mode buffers (which uses org-indent-mode to create virtual indentation), or magit. There is currently no known fix for this, as it can’t be reliably reproduced. Your best bet is to reinstall/rebuild Emacs or disable the errant plugins/modules. e.g.
To disable org-indent-mode:
```
(after! org
  (setq org-startup-indented nil))
    
```
Or disable the :ui doom-dashboard & :tools magit modules (see #1170).
Ligatures and some fonts can cause Emacs to crash. You may want to try a different font, or disable the =:ui ligatures module.

Can’t load my theme; `unable to find theme file for X` errors

This means Emacs can’t find the X-theme.el file for the theme you want to load. Emacs will search for this file in custom-theme-load-path and custom-theme-directory. There are a couple reasons why it can’t be found:

It is generally expected that third party themes will add themselves to custom-theme-load-path, but you will occasionally encounter a theme that does not. This should be reported upstream.
In the meantime, you can get around this by eagerly loading the package:
```
(require 'third-party-theme)
(setq doom-theme 'third-party)
    
```
You’ve appended -theme to the end of your theme’s name.
```
(setq doom-theme 'third-party-theme)
    
```
When you load a theme Emacs searches for X-theme.el. If you set doom-theme to 'third-party-theme, it will search for third-party-theme-theme.el. This is rarely intentional. Omit the -theme suffix.
Did you run doom sync after adding your third party theme plugin’s package! declaration to ~/.doom.d/packages.el?

TRAMP connections hang forever when connecting

You’ll find solutions on the emacswiki.

An upstream package was broken and I can’t update it

Sometimes, if you’ve installed a broken package which was subsequently fixed upstream, you can’t run doom update to get the latest fixes due to evaluation errors.

In those cases, you need to delete the broken local copy before you can install the new one, which is achieved by either deleting it from ~/.emacs.d/.local/straight/repos, or by cycling the module that installs it:

Comment out the broken module/package.
Run doom sync.
Uncomment the module/package.
Run doom sync.

Why do I see ugly indentation highlights for tabs?

Doom highlights non-standard indentation. i.e. Indentation that doesn’t match the indent style you’ve set for that file. Spaces are Doom’s default style for most languages (excluding languages where tabs are the norm, like Go).

There are a couple ways to address this:

Fix your indentation! If it’s highlighted, you have tabs when you should have spaces (or spaces when you should be using tabs).
Two easy commands for that:
- M-x tabify
- M-x untabify

Change indent-tabs-mode (nil = spaces, t = tabs) in ~/.doom.d/config.el:

;; use tab indentation everywhere
(setq-default indent-tabs-mode t)

;; or only in certain modes
(setq-hook! 'sh-mode-hook indent-tabs-mode t) ; shell scripts
(setq-hook! '(c-mode-hook c++-mode-hook) indent-tabs-mode t)  ; C/C++

Use editorconfig to configure code style on a per-project basis. If you enable Doom’s :tools editorconfig module, Doom will recognize .editorconfigrc files.
Or trust in dtrt-indent; a plugin Doom uses to analyze and detect indentation when you open a file (that isn’t in a project with an editorconfig file). This isn’t foolproof, and won’t work for files that have no content in them, but it can help in one-off scenarios.

“clipetty–emit: Opening output file: Permission denied, /dev/pts/29” error

This applies to tmux users, in particular. See spudlyo/clipetty#15 for a solution.

“The directory ~/.emacs.d/server is unsafe” error at startup

If you’re getting this error you must reset the owner of C:\Users\USERNAME\.emacs.d to your own account:

Right-click the ~/.emacs.d/server directory in Windows Explorer,
Click Properties,
Select the “Security” tab,
Click the “Advanced” button,
Select the “Owner” tab
Change the owner to your account name

(source)

My new keybinds don’t work

Emacs has a complex and hierarchical keybinding system. If a global keybind doesn’t take effect, it’s likely that another keymap is in effect with higher priority than the global keymap. For example, non-evil users may have tried something like this, to rebind C-left and C-right:

(map! "<C-left>"  #'something
      "<C-right>" #'something)

Just to find that the rebinding had no effect (i.e. C-h k C-left reports that it’s still bound to sp-backward-slurp-sexp). That’s because these keys are bound in smartparens-mode-map. They need to be unbound for your global keybinds to work:

(map! :after smartparens
      :map smartparens-mode-map
      [C-right] nil
      [C-left] nil)

I use [C-left] because it is easier to type than "<C-left>", but are equivalent; two different ways to refer to the same key.

Files

faq.org

Latest commit

History