#+TITLE: Frequently Asked Questions * Table of Contents :TOC: - [[#general][General]] - [[#why-is-it-called-doom][Why is it called Doom?]] - [[#is-doom-a-fork-of-spacemacspreludeetc][Is Doom a fork of Spacemacs/Prelude/etc?]] - [[#does-doom-work-on-windows][Does Doom work on Windows?]] - [[#is-doom-only-for-vimmers][Is Doom only for vimmers?]] - [[#i-am-a-beginner-can-i-use-doom][I am a beginner. Can I use Doom?]] - [[#how-does-doom-compare-to-spacemacs][How does Doom compare to Spacemacs?]] - [[#why-such-a-complicated-package-management-system][Why such a complicated package management system?]] - [[#how-does-doom-start-up-so-quickly][How does Doom start up so quickly?]] - [[#why-is-startup-time-important-why-not-use-the-daemon][Why is startup time important? Why not use the daemon?]] - [[#how-do-i-use-doom-alongside-other-emacs-configs][How do I use Doom alongside other Emacs configs?]] - [[#why-should-i-use-doom-instead-of-rolling-my-own-config][Why should I use Doom instead of rolling my own config?]] - [[#what-is-the-meaning-behind-dooms-naming-convention-in-its-source-code][What is the meaning behind Doom's naming convention in its source code?]] - [[#what-version-of-doom-am-i-running][What version of Doom am I running?]] - [[#is-discord-the-only-option-for-interacting-with-your-community][Is Discord the only option for interacting with your community?]] - [[#why-is-emacsdoom-slow][Why is Emacs/Doom slow?]] - [[#configuration][Configuration]] - [[#how-do-i-configure-doom-emacs][How do I configure Doom Emacs?]] - [[#does-doom-respect-xdg-directory-conventions][Does Doom respect XDG directory conventions]] - [[#how-do-i-enable-or-disable-a-doom-module][How do I enable or disable a Doom module?]] - [[#how-do-i-change-the-theme][How do I change the theme?]] - [[#how-do-i-change-the-fonts][How do I change the fonts?]] - [[#how-do-i-bind-my-own-keys-or-change-existing-ones][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 get motions to treat underscores as word delimiters?]] - [[#how-do-i-change-the-leaderlocalleader-keys][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 style of line-numbers (or disable them altogether)?]] - [[#how-do-i-change-the-behavior-and-appearance-of-popup-windows][How do I change the behavior and appearance of popup windows?]] - [[#how-do-i-customize-a-theme-or-faces][How do I customize a theme or face(s)?]] - [[#how-do-i-make-a-new-theme][How do I make a new theme?]] - [[#can-doom-be-customized-without-restarting-emacs][Can Doom be customized without restarting Emacs?]] - [[#can-vimevil-be-removed-for-a-more-vanilla-emacs-experience][Can Vim/Evil be removed for a more vanilla Emacs experience?]] - [[#when-should-and-shouldnt-i-use-bindoom][When should and shouldn't I use ~bin/doom~?]] - [[#when-to-run-doom-sync][When to run ~doom sync~]] - [[#how-to-suppress-confirmation-prompts-while-bindoom-is-running][How to suppress confirmation prompts while ~bin/doom~ is running]] - [[#which-terminal-should-i-use][Which terminal should I use?]] - [[#how-do-i-enable-lsp-support-for-insert-language-here][How do I enable LSP support for ?]] - [[#how-to-disable-smartparensautomatic-parentheses-completion][How to disable smartparens/automatic parentheses completion?]] - [[#how-do-i-maximizefullscreen-emacs-on-startup][How do I maximize/fullscreen Emacs on startup?]] - [[#how-do-i-sharesync-my-config-between-multiple-computers][How do I share/sync my config between multiple computers?]] - [[#package-management][Package Management]] - [[#how-do-i-install-a-package-from-elpa][How do I install a package from ELPA?]] - [[#how-do-i-install-a-package-from-githubanother-source][How do I install a package from github/another source?]] - [[#how-do-i-change-where-an-existing-package-is-installed-from][How do I change where an existing package is installed from?]] - [[#how-do-i-disable-a-package-completely][How do I disable a package completely?]] - [[#how-do-i-reconfigure-a-package-included-in-doom][How do I reconfigure a package included in Doom?]] - [[#where-does-straight-clonebuild-packages-to][Where does straight clone/build packages to?]] - [[#defaults][Defaults]] - [[#why-ivy-over-helm][Why Ivy over Helm?]] - [[#why-are-there-no-default-keybinds-for-smartparens-for-evil-users][Why are there no default keybinds for Smartparens (for evil users)?]] - [[#why-do-non-evil-users-get-expand-region-but-not-evil-users][Why do non-evil users get expand-region, but not evil users?]] - [[#why-not-use-exec-path-from-shell-instead-of-doom-env][Why not use exec-path-from-shell instead of ~doom env~?]] - [[#why-wsbutler-over-delete-trailing-whitespace-or-whitespace-cleanup][Why wsbutler over delete-trailing-whitespace or whitespace-cleanup?]] - [[#emacs-lisp][Emacs Lisp]] - [[#why-do-you-quote-some-symbols-with-symbol][Why do you quote some symbols with ~#'symbol~?]] - [[#common-issues][Common Issues]] - [[#i-get-the-vanilla-emacs-splash-screen-at-startup][I get the vanilla Emacs splash screen at startup]] - [[#i-see-a-blank-scratch-buffer-at-startup][I see a blank scratch buffer at startup]] - [[#strange-or-incorrect-icons-are-displayed-everywhere][Strange (or incorrect) icons are displayed everywhere]] - [[#void-variable-and-void-function-errors-on-startup][~void-variable~ and ~void-function~ errors on startup]] - [[#doom-cant-find-my-executablesdoesnt-inherit-the-correct-path][Doom can't find my executables/doesn't inherit the correct ~PATH~]] - [[#theres-artefacting-on-my-icon-fonts-in-gui-emacs-956][There's artefacting on my icon fonts in GUI Emacs (#956)]] - [[#the-s-and-s-keys-dont-behave-like-they-do-in-vimevil-1307][The =s= and =S= keys don't behave like they do in vim/evil (#1307)]] - [[#changes-to-my-config-arent-taking-effect][Changes to my config aren't taking effect]] - [[#the-frame-goes-black-on-macos-while-in-full-screen-mode][The frame goes black on MacOS, while in full-screen mode]] - [[#doom-crashes-when][Doom crashes when...]] - [[#cant-load-my-theme-unable-to-find-theme-file-for-x-errors][Can't load my theme; ~unable to find theme file for X~ errors]] - [[#tramp-connections-hang-forever-when-connecting][TRAMP connections hang forever when connecting]] - [[#an-upstream-package-was-broken-and-i-cant-update-it][An upstream package was broken and I can't update it]] - [[#why-do-i-see-ugly-indentation-highlights-for-tabs][Why do I see ugly indentation highlights for tabs?]] - [[#clipetty--emit-opening-output-file-permission-denied-devpts29-error]["clipetty--emit: Opening output file: Permission denied, /dev/pts/29" error]] - [[#the-directory-emacsdserver-is-unsafe-error-at-startup]["The directory ~/.emacs.d/server is unsafe" error at startup]] - [[#my-new-keybinds-dont-work][My new keybinds don't work]] * General ** Why is it called Doom? It's an homage to idsoftware's classic game, whose [[https://github.com/id-Software/DOOM][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 [[file:getting_started.org::On Windows][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 [[file:../modules/editor/evil/README.org::Removing evil-mode][removing evil-mode]] section in the [[file:../modules/editor/evil/README.org][: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 [[https://discord.gg/qvGgnVx][if you ask]] -- but expect a hefty commitment and a bumpy journey. Don't pass up on the [[file:index.org][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 [[https://www.reddit.com/r/emacs/comments/6pa0oq/quickstart_tutorial_for_emacs_newbies_with_doom/dkp1bhd/][reddit answer]] to this question by [[https://github.com/gilbertw1][@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: 1. *Scriptability:* package management should be shell-scriptable, so updating can be automated. 2. *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. 3. *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. 4. *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. 5. *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: #+BEGIN_SRC emacs-lisp (setq gc-cons-threshold most-positive-fixnum ; 2^61 bytes gc-cons-percentage 0.6) ;; ... your emacs config here ... #+END_SRC 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. #+BEGIN_SRC emacs-lisp (add-hook 'emacs-startup-hook (lambda () (setq gc-cons-threshold 16777216 ; 16mb gc-cons-percentage 0.1))) #+END_SRC 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: #+BEGIN_SRC emacs-lisp (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) #+END_SRC Another alternative (which is [[https://github.com/hlissner/doom-emacs/blob/develop/core/core.el#L269-L274][what Doom uses]]) is the [[https://gitlab.com/koral/gcmh/][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 [[https://github.com/hlissner/doom-emacs/tree/develop/core/cli/autoloads.el][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): #+BEGIN_SRC emacs-lisp (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) #+END_SRC 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!* #+BEGIN_SRC emacs-lisp ;; 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) #+END_SRC *** 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=: #+BEGIN_SRC elisp (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) #+END_SRC 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 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!): #+BEGIN_SRC emacs-lisp (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))) #+END_SRC Don't forget to restore ~file-name-handler-alist~, otherwise TRAMP won't work and compressed/encrypted files won't open. *** Use [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Lexical-Binding.html][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: + [[http://nullprogram.com/blog/2017/01/30/]["How to Write Fast(er) Emacs Lisp."]] + [[http://nullprogram.com/blog/2016/12/22/]["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 [[https://github.com/alpha22jp/atomic-chrome][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 [[https://github.com/plexus/chemacs][Chemacs]]. Think of it as a bootloader for Emacs. You'll [[file:getting_started.org::*Alongside other Emacs configs (with Chemacs)][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: #+BEGIN_SRC bash # 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 #+END_SRC #+begin_quote 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. #+end_quote ** Why should I use Doom instead of rolling my own config? Two reasons: 1. *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! 2. *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 [[file:contributing.org::*Conventions][an overview of Doom's code conventions]] in the [[file:contributing.org][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 [[https://www.discourse.org][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? 1. Upgrade to Emacs 27. This should yield a noteworthy gain in general performance, particularly for LSP users. 2. Try out [[http://akrl.sdf.org/gccemacs.html][gccemacs]], which promises significant strides in Emacs performance, but can be a bit of a hassle to set up. There are packages available for [[https://aur.archlinux.org/packages/emacs-native-comp-git/][Arch Linux]], [[https://github.com/flatwhatson/guix-channel][Guix]] and [[https://github.com/nix-community/emacs-overlay][Nix users]]. [[https://www.emacswiki.org/emacs/GccEmacs][More information available on EmacsWiki]]. 3. 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=. 4. Turn off line numbers ~(setq display-line-numbers-type nil)~. It's known to slow down scrolling, in particular. 5. 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: #+BEGIN_SRC elisp (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)) #+END_SRC 6. 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. 7. Try replacing the =:ui modeline= module with =:ui (modeline +light)=. There are aspects of the default modeline that can be unpredictably slow. 8. 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 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 [[file:getting_started.org::Customize][Customize section]] in the [[file:getting_started.org][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 "[[file:getting_started.org::*Configuration modules][Configuration modules]]" section of the [[file:getting_started.org][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. #+BEGIN_SRC emacs-lisp ;;; add to ~/.doom.d/config.el (setq doom-theme 'doom-tomorrow-night) ;; or (load-theme 'doom-tomorrow-night t) #+END_SRC #+begin_quote 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. #+end_quote *** Installing a third party theme To install a theme from a third party plugin, say, [[https://github.com/bbatsov/solarized-emacs][solarized]], you need only install it, then load it: #+BEGIN_SRC emacs-lisp ;;; add to ~/.doom.d/packages.el (package! solarized-theme) ;;; add to ~/.doom.d/config.el (setq doom-theme 'solarized-dark) #+END_SRC 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 [[https://wiki.archlinux.org/index.php/X_Logical_Font_Description][xlfd font string]]. e.g. #+BEGIN_SRC emacs-lisp ;;; 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)) #+END_SRC ** 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 [[file:api.org][in docs/api]]). There are also live examples ~map!~'s usage in [[file:../modules/config/default/+evil-bindings.el][config/default/+evil-bindings.el]]. ** How do I get motions to treat underscores as word delimiters? (This explanation comes from [[https://github.com/emacs-evil/evil#underscore-_-is-not-a-word-character][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: #+BEGIN_SRC emacs-lisp (modify-syntax-entry ?_ "w") #+END_SRC 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.: #+BEGIN_SRC emacs-lisp ;; 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")) #+END_SRC ** 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. #+BEGIN_SRC emacs-lisp ;;; add to ~/.doom.d/config.el (setq doom-leader-key "," doom-localleader-key "\\") #+END_SRC ** 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 #+BEGIN_SRC elisp ;;; 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) #+END_SRC *** 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: #+begin_example t normal line numbers 'relative relative line numbers 'visual relative line numbers in screen space nil no line numbers #+end_example For example: #+BEGIN_SRC elisp ;;; add to ~/.doom.d/config.el (setq display-line-numbers-type 'relative) #+END_SRC You'll find more precise documentation on the variable through = v display-line-numbers-type= (== 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 [[file:../modules/ui/popup/README.org::Configuration][: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. #+begin_quote 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. #+end_quote ** 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: #+BEGIN_SRC elisp ;; add to ~/.doom.d/config.el (setq doom-theme 'XYZ) ;; or (load-theme 'XYZ t) #+END_SRC ** 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 [[file:../modules/editor/evil/README.org::Removing evil-mode][Removing evil-mode]] section in [[file:../modules/editor/evil/README.org][: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: #+BEGIN_SRC bash git pull doom sync doom update #+END_SRC ** 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: #+BEGIN_SRC bash doom -y update doom --yes update YES=1 doom update #+END_SRC ** 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 [[file:../modules/term/vterm/README.org][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 ? Doom supports LSP, but it is not enabled by default. To enable it, you must: 1. Enable the =:tools lsp= module, 2. Enable the =+lsp= flag for the appropriate modules you want LSP support for (e.g. =:lang (python +lsp)= or =:lang (rust +lsp)=), 3. Install the prerequisite LSP servers through your package manager or other means. You can find a list of supported servers on [[https://github.com/emacs-lsp/lsp-mode#supported-languages][the lsp-mode project page]]. 4. 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=: #+BEGIN_SRC elisp (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 #+END_SRC ** How to disable smartparens/automatic parentheses completion? Some outdated sources may tell you to do this, *but it is no longer correct*: #+BEGIN_SRC elisp (after! smartparens (smartparens-global-mode -1)) #+END_SRC Instead, use the following: #+BEGIN_SRC elisp (remove-hook 'doom-first-buffer-hook #'smartparens-global-mode) #+END_SRC 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? #+BEGIN_SRC elisp (add-to-list 'initial-frame-alist '(fullscreen . maximized)) #+END_SRC 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 "[[file:getting_started.org::*Installing packages][Installing packages]]" section of the [[file:getting_started.org][Getting Started]] guide. ** How do I install a package from github/another source? See the "[[file:getting_started.org::*Installing packages from external sources][Installing packages from external sources]]" section of the [[file:getting_started.org][Getting Started]] guide. ** How do I change where an existing package is installed from? See the "[[file:getting_started.org::*Changing a recipe for a included package][Changing a recipe for a included package]]" section of the [[file:getting_started.org][Getting Started]] guide. ** How do I disable a package completely? See the "[[file:getting_started.org::*Disabling packages][disabling packages]]" section of the [[file:getting_started.org][Getting Started]] guide. ** How do I reconfigure a package included in Doom? See the "[[file:getting_started.org::*Configuring packages][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. #+BEGIN_QUOTE There are also text objects for xml tags (=x=), C-style function arguments (=a=), angle brackets, and single/double quotes. #+END_QUOTE 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: #+BEGIN_SRC elisp ;;; 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) #+END_SRC ** Why not use exec-path-from-shell instead of ~doom env~? The ~doom env~ approach is a faster and more reliable solution. 1. ~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. 2. ~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: #+BEGIN_SRC emacs-lisp ;;; 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)) #+END_SRC ** 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: 1. 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. 2. 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: 1. Your shell configuration doesn't configure ~PATH~ correctly. If ~which ~ doesn't emit the path you expect on the command line then this is likely the case. 2. 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. 3. 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. [[https://discord.gg/qvGgnVx][Our Discord]] is a good place to ask about it. ** There's artefacting on my icon fonts in GUI Emacs ([[https://github.com/hlissner/doom-emacs/issues/956][#956]]) Check your font rendering settings. Changing the RGBA order to "rgba" will often fix this issue. See [[https://github.com/hlissner/doom-emacs/issues/956][#956]] for details. ** The =s= and =S= keys don't behave like they do in vim/evil ([[https://github.com/hlissner/doom-emacs/issues/1307][#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: #+BEGIN_SRC emacs-lisp ;; in ~/.doom.d/config.el (after! evil-snipe (evil-snipe-mode -1)) #+END_SRC ** Changes to my config aren't taking effect 1. Make sure you don't have both =~/.doom.d= and =~/.config/doom= directories. Doom will ignore the former if the latter exists. 2. 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: 1. Avoid MacOS native fullscreen by maximizing Emacs instead, 2. Disable childframes (controlled by the =+childframe= flag on the modules that support it), 3. 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: #+BEGIN_SRC emacs-lisp (after! org (setq org-startup-indented nil)) #+END_SRC Or disable the =:ui doom-dashboard= & =:tools magit= modules (see [[https://github.com/hlissner/doom-emacs/issues/1170][#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: 1. It is generally expected that third party themes will [[https://github.com/hlissner/emacs-doom-themes/blob/master/doom-themes.el#L400-L405][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: #+BEGIN_SRC elisp (require 'third-party-theme) (setq doom-theme 'third-party) #+END_SRC 2. You've appended ~-theme~ to the end of your theme's name. #+BEGIN_SRC elisp (setq doom-theme 'third-party-theme) #+END_SRC 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. 3. 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 [[https://www.emacswiki.org/emacs/TrampMode#toc7][on the emacswiki]]. ** An upstream package was broken and I can't update it Sometimes, if you've installed a [[https://github.com/hlissner/doom-emacs/issues/2213][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: 1. Comment out the broken module/package. 2. Run ~doom sync~. 3. Uncomment the module/package. 4. Run ~doom sync~. ** Why do I see ugly indentation highlights for tabs? [[https://github.com/hlissner/doom-emacs/blob/develop/core/core-ui.el#L132-L150][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: 1. 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= 2. Change ~indent-tabs-mode~ (nil = spaces, t = tabs) in =~/.doom.d/config.el=: #+BEGIN_SRC elisp ;; 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++ #+END_SRC 3. Use [[https://editorconfig.org/][editorconfig]] to configure code style on a per-project basis. If you enable Doom's =:tools editorconfig= module, Doom will recognize =.editorconfigrc= files. 4. 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 https://github.com/spudlyo/clipetty/issues/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: 1. Right-click the =~/.emacs.d/server= directory in Windows Explorer, 2. Click Properties, 3. Select the "Security" tab, 4. Click the "Advanced" button, 5. Select the "Owner" tab 6. Change the owner to your account name ([[https://stackoverflow.com/questions/885793/emacs-error-when-calling-server-start][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=: #+BEGIN_SRC elisp (map! "" #'something "" #'something) #+END_SRC 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: #+BEGIN_SRC elisp (map! :after smartparens :map smartparens-mode-map [C-right] nil [C-left] nil) #+END_SRC #+begin_quote I use ~[C-left]~ because it is easier to type than ~""~, but are equivalent; two different ways to refer to the same key. #+end_quote