- General
- Why is it called Doom?
- Is Doom a fork of Spacemacs/Prelude/etc?
- Does Doom work on Windows?
- Is Doom only for vimmers?
- I am a beginner. Can I use Doom?
- How does Doom compare to Spacemacs?
- Why such a complicated package management system?
- How does Doom start up so quickly?
- Why is startup time important? Why not use the daemon?
- How do I use Doom alongside other Emacs configs?
- Why should I use Doom instead of rolling my own config?
- What is the meaning behind Doom’s naming convention in its source code?
- What version of Doom am I running?
- Is Discord the only option for interacting with your community?
- Why is Emacs/Doom slow?
- Configuration
- How do I configure Doom Emacs?
- Does Doom respect XDG directory conventions
- How do I enable or disable a Doom module?
- How do I change the theme?
- How do I change the fonts?
- How do I bind my own keys (or change existing ones)?
- How do I get motions to treat underscores as word delimiters?
- How do I change the leader/localleader keys?
- How do I change the style of line-numbers (or disable them altogether)?
- How do I change the behavior and appearance of popup windows?
- How do I customize a theme or face(s)?
- How do I make a new theme?
- Can Doom be customized without restarting Emacs?
- Can Vim/Evil be removed for a more vanilla Emacs experience?
- When should and shouldn’t I use
bin/doom
? - When to run ~doom sync~
- How to suppress confirmation prompts while
bin/doom
is running - Which terminal should I use?
- How do I enable LSP support for <insert language here>?
- How to disable smartparens/automatic parentheses completion?
- How do I maximize/fullscreen Emacs on startup?
- How do I share/sync my config between multiple computers?
- Package Management
- Defaults
- Emacs Lisp
- Common Issues
- I get the vanilla Emacs splash screen at startup
- I see a blank scratch buffer at startup
- Strange (or incorrect) icons are displayed everywhere
- ~void-variable~ and
void-function
errors on startup - Doom can’t find my executables/doesn’t inherit the correct ~PATH~
- There’s artefacting on my icon fonts in GUI Emacs (#956)
- The
s
andS
keys don’t behave like they do in vim/evil (#1307) - Changes to my config aren’t taking effect
- The frame goes black on MacOS, while in full-screen mode
- Doom crashes when…
- Can’t load my theme;
unable to find theme file for X
errors - TRAMP connections hang forever when connecting
- An upstream package was broken and I can’t update it
- Why do I see ugly indentation highlights for tabs?
- “clipetty–emit: Opening output file: Permission denied, /dev/pts/29” error
- “The directory ~/.emacs.d/server is unsafe” error at startup
- My new keybinds don’t work
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.
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.
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!
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.
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.
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.
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.
Doom employs a number of techniques to cut down startup time. Here are its most effective techniques:
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.
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.
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)
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 needorg-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:https:// URLs. Since org-protocol depends on org, this can be expensive to load yourself, so Doom loads as soon as a org-protocol:https:// 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, populatesgs
, then simulates thegs
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.
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 this 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:
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?
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.
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.
You’ll find an overview of Doom’s code conventions in the contributing guide.
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.
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.
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
(orC-n
) to scroll. Evil users can scroll long distances withC-d
andC-u
, for instance, or evil-easymotion undergs
, to avoid that slowness. Otherwise, use search mechanisms to move around, like isearch (C-s
) or evil-search (/
).
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
your 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.
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
.
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.
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 andload-theme
loads the theme immediately. Which you choose depends on your needs, but I recommend settingdoom-theme
because, if I later discover a better way to load themes, I can easily change how Doom usesdoom-theme
, but I can’t (easily) control how you use theload-theme
function.
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.
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 fordoom-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))
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.
(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"))
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 "\\")
Doom uses the display-line-numbers
package, which is built into Emacs 26+.
;;; 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)
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).
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
.
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).
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
orM-x customize-face
. Do not use these commands. Doom does not support them and their settings could break any time.
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)
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 thegr
operator for evil users) oreval-last-sexp
(bound toC-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 providesM-x doom/reload
for your convenience (bound toSPC h r r
andC-h r r
). This runsdoom 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 toSPC q r
).
Yes! See the Removing evil-mode section in :editor evil’s documentation.
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
As a rule of thumb you should run doom sync
whenever you:
- Update Doom with
git pull
instead ofdoom 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.
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
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 openvterm
, 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.
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
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.
(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
.
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.
See the ”Installing packages” section of the Getting Started guide.
See the ”Installing packages from external sources” section of the Getting Started guide.
See the ”Changing a recipe for a included package” section of the Getting Started guide.
See the ”disabling packages” section of the Getting Started guide.
See the ”configuring packages” section of the Getting Started guide.
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
.
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.
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.
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 byio
to expand to a symbol, thenib
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)
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 onlyPATH
andMANPATH
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))
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!
#'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.
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.
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.
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).
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 yourdoom!
block in~/.doom.d/init.el
, or addpackage!
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 runningdoom install
(this will take a while).
- Running
The two most common causes for PATH issues in Doom are:
- Your shell configuration doesn’t configure
PATH
correctly. Ifwhich <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))
- 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, rundoom 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.
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.
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.
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 setdoom-theme
to'third-party-theme
, it will search forthird-party-theme-theme.el
. This is rarely intentional. Omit the-theme
suffix. - Did you run
doom sync
after adding your third party theme plugin’spackage!
declaration to~/.doom.d/packages.el
?
You’ll find solutions on the emacswiki.
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
.
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.
This applies to tmux users, in particular. See spudlyo/clipetty#15 for a solution.
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)
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.