Doom Emacs

Doom Emacs is a configuration framework (a "distribution") for GNU Emacs that preconfigures Emacs to behave like a modern, Vim-style editor. It ships with sane defaults, fast startup, a module system, and tight integration of evil-mode (Vim emulation).

Vanilla Emacs is a blank slate; you write all configuration yourself. Doom gives you a curated, opinionated, performance-focused setup with a declarative module system, a leader-key based keybinding scheme, and a CLI (doom) to manage it.

Both are Vim-friendly distributions. Doom prioritizes startup speed and minimal, explicit configuration; Spacemacs is heavier, more abstracted ("layers"), and generally slower to start. Doom favors readable Emacs Lisp over heavy macros.

No. It is configuration layered on top of stock GNU Emacs. You still install Emacs separately; Doom configures it.

Speed (fast startup via lazy loading and native compilation), a clean module system, good defaults, and discoverability through which-key and the leader key.

A recent stable Emacs (Emacs 27.1 minimum historically; current Doom targets Emacs 28/29/30). Emacs 29+ with native compilation (libgccjit) is recommended.

Native compilation (gccjit) compiles Emacs Lisp to native machine code, significantly improving runtime performance. Emacs built --with-native-compilation lets Doom and packages run faster after an initial compile.

Git, Emacs (28+ recommended), ripgrep (rg), and fd (find alternative). Optional but recommended: a Nerd Font / patched font for icons, and language tools (LSP servers, shellcheck, etc.).

Clone Doom into your Emacs config dir and run the installer:

git clone --depth 1 https://github.com/doomemacs/doomemacs ~/.config/emacs
~/.config/emacs/bin/doom install

Two locations: the Doom core/runtime in ~/.config/emacs (or ~/.emacs.d), and your personal config in ~/.config/doom (or ~/.doom.d).

Typically %USERPROFILE%\.config\emacs for the core and %USERPROFILE%\.doom.d or %USERPROFILE%\.config\doom for your config. Install Emacs (e.g. via the official Windows build or scoop), plus git, ripgrep, and fd on the PATH.

Start the Emacs daemon (emacs --daemon) and connect with emacsclient. This makes new frames open near-instantly since Emacs is already loaded.

Add ~/.config/emacs/bin (or ~/.emacs.d/bin) to your shell PATH so you can call doom from anywhere.

It clones/installs all packages for your enabled modules, generates environment files, compiles, and runs doom sync for the first time.

doom sync reconciles your config (init.el, packages.el) with installed packages. Run it whenever you edit init.el or packages.el (enable/disable modules or add packages).

It diagnoses your installation: missing dependencies, broken fonts, misconfigured servers, byte-compile warnings. Run it first when something is wrong.

It pulls the latest Doom core, updates all packages to pinned versions, and syncs. It is the standard way to update Doom.

Use git in ~/.config/emacs to checkout the previous commit, then run doom sync. Doom pins package versions, so a checkout restores the prior known-good state.

doom sync, doom upgrade, doom doctor, doom install, doom build (doom sync -b), doom purge, doom env, doom compile.

It captures your shell environment into an env file that Emacs loads, so GUI Emacs inherits your PATH and variables. Re-run after changing your shell environment.

It removes orphaned/unused packages and old build artifacts to reclaim disk space.

It byte-compiles (and native-compiles) installed packages, improving performance.

doom upgrade updates both; to update packages alone, edit pins in packages.el or use doom sync -u (update) depending on Doom version. Generally doom upgrade is the supported path.

The -u flag updates packages to their latest allowed versions during sync.

init.el (enable/disable modules), packages.el (declare extra/override packages), and config.el (your personal Emacs Lisp configuration).

The doom! block listing enabled modules and their flags. You toggle features here, not write logic. After editing, run doom sync.

All your personal customization: settings, keybindings, package config, hooks, and Emacs Lisp. It is loaded at startup.

Package declarations: (package! foo) to install extra packages, (package! bar :disable t) to disable, or pinning/recipe overrides. Run doom sync after edits.

~/.config/doom on XDG systems, or ~/.doom.d (legacy). Doom checks both.

The variable doom-user-dir holds your private config path; doom-emacs-dir holds the core path.

Emacs writes M-x customize settings to a custom file. Doom isolates this; prefer configuring in config.el with setq=/=after! over the Customize UI for reproducibility.

SPC h r r (doom/reload) reloads, but a full restart is more reliable after big changes. For pure elisp edits, M-x eval-buffer or SPC m e b in config.el.

Doom groups functionality into modules organized as :category module, e.g. :lang python, :tools magit, :editor evil. You enable them in the doom! block.

Uncomment or add it in init.el's doom! block, then run doom sync and restart.

Flags refine a module's behavior, written with +: e.g. (python +lsp +pyright) or (org +pretty +roam2). They toggle optional features within a module.

:input :completion :ui :editor :emacs :term :checkers :tools :os :lang :email :app :config.

Browse ~/.config/emacs/modules, read SPC h d m (Doom module docs), or check the Doom documentation. Each module has a README describing flags.

Completion frameworks: e.g. vertico (minibuffer completion), corfu or company (in-buffer completion), helm=/=ivy (older). Pick one minibuffer + one in-buffer.

Enables Vim emulation (evil-mode); the +everywhere flag extends Vim keybindings into more Emacs interfaces (dired, magit, etc.).

Doom's sensible default settings and keybindings; (default +bindings +smartparens) adds the standard leader-key bindings and smartparens.

Remove its module/flag from init.el and doom sync, or in packages.el add (package! x :disable t).

Doom will warn (run doom doctor). Enable only one minibuffer completion system and one in-buffer completion system.

Evil is the Vim emulation layer. Doom enables it by default so you edit with modal (normal/insert/visual) Vim keybindings.

Normal, Insert, Visual (char/line/block), Replace, Operator-pending, Motion, and Emacs state (C-z toggles Emacs state).

Press C-z to toggle evil-emacs-state, restoring native Emacs keybindings.

Press ESC, or C-g, or the configured jk escape sequence if enabled (evil-escape).

A package letting you exit insert/visual mode by typing a quick two-key sequence (default often jk or fd), avoiding reaching for ESC.

:%s/old/new/g (evil ex command), like in Vim. Add c for confirmation: :%s/old/new/gc.

Use Vim text objects: ciw (change inner word), di" (delete inside quotes), ya( (yank around parens), etc. Doom adds extra objects via evil-textobj-*.

gd jumps to definition (go-to-definition), wired to LSP/xref/tags depending on the language.

gc is the comment operator (from evil-commentary / evil-nerd-commenter): gcc comments a line, gc + motion comments a region.

C-a increments, C-x decrements (evil-numbers / Doom binding). Note C-x is rebound from the Emacs prefix in normal state.

q followed by a register (e.g. qa) records into register a; q stops; @a plays; @@ repeats the last macro — standard Vim.

m{a-z} sets a mark, '{a-z} jumps to it; C-o / C-i move backward/forward in the jump list.

SPC (space) in normal/visual state is the Doom leader key, prefix for almost all commands. In insert/Emacs state the leader is M-SPC or C-c depending on config.

SPC m (or , in normal state) is the localleader — mode-specific commands for the current major mode (e.g. org, python).

Press SPC and wait: which-key shows a popup of available next keys. This is the primary discovery mechanism.

Find file (find-file) — opens the file browser/minibuffer to open a file.

find-file starting at the current directory (quick file open).

Switch buffer — lists open buffers to switch between.

Switch project (Projectile) — lists known projects to open.

M-x equivalent — execute an Emacs command by name (execute-extended-command).

eval-expression — evaluate an Emacs Lisp expression in the minibuffer.

Help: SPC h f describe function, SPC h v describe variable, SPC h k describe key, SPC h d Doom-specific help (docs, modules, news).

SPC : (M-x) and type a fuzzy command name, or SPC h b b to search all bindings.

Use Doom's map! macro:

(map! :leader
      :desc "Format buffer" "c f" #'+format/buffer)

(map! :map python-mode-map
      :n "gh" #'lsp-describe-thing-at-point)

:n scopes to normal state; :map scopes to a keymap.

:n normal, :i insert, :v visual, :m motion, :e emacs, :g global (all/no state), :o operator. They scope the binding to evil states.

Bind it to nil:

(map! :n "C-a" nil)

A buffer holds content (a file or output); a window is a viewport showing a buffer; a frame is an OS-level window containing windows.

SPC w v vertical split, SPC w s horizontal split, SPC w d close window. Or evil: C-w v, C-w s, C-w c.

SPC w h/j/k/l or C-w h/j/k/l to move by direction; SPC w w to cycle.

SPC b k (kill-buffer) or SPC b d. SPC b K kills all other buffers.

Workspaces (via persp-mode / :ui workspaces) are named, isolated sets of buffers and window layouts — like tabs/sessions. Switch with SPC TAB.

SPC TAB n new, SPC TAB [ / SPC TAB ] previous/next, SPC TAB 1..9 by number, SPC TAB . switch by name.

Opening a project with SPC p p can spawn a new workspace, isolating its buffers from other projects.

SPC q s save session, SPC q l restore last session. Workspaces persist layout and buffers.

Switch to the last (alternate) buffer — quick toggle between two buffers.

Projectile is project management: it detects project roots (.git, etc.) and gives project-scoped commands for finding files, searching, and running commands.

SPC SPC (projectile-find-file) or SPC p f.

SPC s p (+default/search-project) runs ripgrep across the project. SPC s b searches the current buffer.

ripgrep (rg) for content search and fd for filename search; both must be installed and on PATH.

With Vertico-based completion, consult provides live, previewable search commands like consult-ripgrep for incremental project-wide search.

SPC f r (recent files) lists files from history.

SPC f d or SPC d opens dired for the current directory; navigate with evil keys.

The startup screen showing recent files, projects, and bookmarks. SPC b H or visiting *doom* returns to it.

SPC RET (bookmark-jump); set with SPC f b or bookmark-set.

SPC f R rename/move, SPC f D delete current file.

SPC f y copies the file path to the kill ring (yank).

A lightweight vertical minibuffer completion UI (the modern Doom default in the :completion vertico module), replacing Ivy/Helm.

A completion style allowing space-separated, order-independent fuzzy matching of candidates. It pairs with Vertico.

A package adding rich annotations (docs, file sizes, keybindings) beside minibuffer candidates.

embark provides context actions on the candidate at point (like a right-click menu) — act on files, buffers, symbols from the minibuffer. Often SPC a or C-;.

Both are in-buffer (at-point) completion popups. company is the older, mature choice; corfu is the newer, lighter, completion-at-point-native alternative.

C-SPC or TAB (config dependent) invokes company/corfu; with LSP it shows symbol completions.

C-n / C-p (or arrow keys) move; RET or TAB accepts; C-g cancels.

yasnippet expands abbreviations into templates with fields you tab through. Doom's :editor snippets module enables it; SPC i s inserts a snippet.

SPC i S (or yas-new-snippet) and save into ~/.config/doom/snippets/<mode>/.

A powerful Emacs major mode for notes, outlining, task management, agendas, literate programming, and document authoring in plain text.

Add flags in init.el: (org +pretty +roam2 +journal +dragndrop) etc., then doom sync.

The base folder for org files/agenda. Set early in config.el:

(setq org-directory "~/org/")

Set it before Org loads for agenda to pick it up.

Type a headline and prefix with TODO, or SPC m t to cycle TODO state on a headline. S-LEFT/RIGHT cycles keywords.

SPC m d s schedule, SPC m d d deadline (or org-schedule / org-deadline). Adds a timestamp the agenda reads.

SPC o A (or org-agenda) opens the agenda dispatcher; choose a view (day/week, TODO list).

A quick note/task capture system. SPC X or SPC n n triggers a capture template to file notes into predefined locations.

Set org-capture-templates in config.el via after! org:

(after! org
  (add-to-list 'org-capture-templates
    '("t" "Todo" entry (file+headline "inbox.org" "Tasks")
      "* TODO %?\n  %U")))

#+begin_src lang ... #+end_src blocks you can execute in-buffer with C-c C-c, enabling literate programming. Enable languages via org-babel-load-languages.

A Zettelkasten-style note system (+roam2 flag) for linked, networked notes with backlinks. SPC n r f find/create a note, SPC n r i insert a link.

Exporting org documents to HTML, PDF (via LaTeX), Markdown, etc., via the export dispatcher SPC m e (org-export-dispatch).

org-babel-tangle (SPC m b t) extracts source blocks into separate files — useful for literate config.

The +pretty flag enables org-modern / superstar bullets, prettified entities, and better headings.

Magit is the premier Git porcelain for Emacs — a full-featured, fast Git interface driven by single keystrokes. Enabled via :tools magit.

SPC g g (magit-status) opens the status buffer for the current repo.

In the status buffer, move to a file/hunk and press s to stage, u to unstage. S stages all.

Press c c to start a commit, write the message, then C-c C-c to finalize.

P opens the push transient, F the pull transient; choose remote/branch via the menu.

SPC g f l file log, or in Magit l l for the log; press RET on a commit to view its diff.

The popup menu (Magit/Transient) listing available options and switches for an action (push, log, rebase). You toggle flags then trigger.

r i in the log/status, select the base commit; reorder/squash/edit in the rebase buffer, then C-c C-c.

Use smerge-mode (auto-enabled) — keybindings under SPC g or C-c ^ to keep upper/lower/both; Magit shows conflicted files in status.

The :ui vc-gutter module shows added/changed/removed line indicators in the fringe. SPC g [ / SPC g ] jump between hunks.

SPC g t steps through a file's historical revisions one commit at a time to see how it changed.

SPC g B (magit-blame) annotates each line with its last-changing commit/author.

LSP (Language Server Protocol) provides IDE features (completion, diagnostics, go-to-def) via external servers. Doom integrates via the :tools lsp module (lsp-mode or eglot).

Add the +lsp flag to the language module, e.g. (python +lsp), enable :tools lsp, install the language server, then doom sync.

Both are LSP clients. lsp-mode is feature-rich and heavier; eglot (+eglot flag) is minimal and built into Emacs 29+. Choose one in the :tools lsp module.

gd go to definition, gD or SPC c D find references, K or SPC c k show docs at point.

SPC c r (lsp-rename / eglot-rename) renames the symbol and updates references.

:checkers syntax (Flycheck/Flymake) shows diagnostics; SPC c x lists errors, ] e / [ e jump to next/previous.

Both are on-the-fly syntax checkers. flycheck is the long-standing third-party option; flymake is built-in and used by eglot. The :checkers syntax module configures one.

SPC c f (+format/buffer) via the :editor format module, using formatters like prettier, black, gofmt per language.

Many lang modules add a REPL under SPC m r or SPC o r (e.g. Python SPC m r r). :tools eval enables SPC c e to eval regions.

gcc a line, gc + motion a region (evil), or SPC c c region.

za toggle fold, zR open all, zM close all (evil-vimish-fold / origami / built-in hideshow). LSP can provide semantic folding.

Enable its :lang module in init.el (e.g. rust, go, java), add flags like +lsp, install toolchain + language server, doom sync, restart.

Tree-sitter provides fast, accurate syntax parsing. Emacs 29+ has built-in tree-sitter modes; Doom modules increasingly support +tree-sitter flags for better highlighting and structural editing.

The :tools debugger module enables dap-mode (with lsp) or realgud. SPC c d starts a debug session; set breakpoints and step through.

Set doom-theme in config.el:

(setq doom-theme 'doom-one)

Browse themes live with SPC h t (load-theme).

The doom-themes package bundles many themes (doom-one, doom-dracula, doom-gruvbox, etc.). You can also load any Emacs theme.

Set doom-font (and optionally doom-variable-pitch-font, doom-big-font) in config.el:

(setq doom-font (font-spec :family "JetBrains Mono" :size 14))

You need a Nerd Font / icon font installed. Run M-x nerd-icons-install-fonts (or all-the-icons-install-fonts on older Doom) and restart.

The modeline (status bar) is doom-modeline. Configure via after! doom-modeline and setq doom-modeline-* variables (e.g. height, icons, buffer name style).

display-line-numbers-type controls it:

(setq display-line-numbers-type 'relative)

t absolute, 'relative relative, 'visual, or nil off.

SPC = + or C-+ / C-- adjust text-scale; SPC t b toggles doom-big-font (zen/present mode).

The :ui zen module centers text and removes distractions for writing. Toggle with SPC t z.

The :ui treemacs module gives a project tree. SPC o p toggles treemacs; navigate with evil keys.

Set +doom-dashboard-banner-file and +doom-dashboard-banner-dir in config.el to point at a custom image.

:term vterm (fast, libvterm-based, recommended), :term eshell (elisp shell), :term shell and :term term. vterm needs compilation of a native module.

SPC o t opens a terminal in the current window; SPC o T in a popup. With vterm, SPC o t or M-x +vterm/here.

An Emacs-implemented shell mixing shell syntax with Emacs Lisp; portable across OSes and integrated with Emacs buffers. SPC o e opens it.

M-x async-shell-command or SPC : then the command; output goes to a buffer without blocking Emacs.

On GUI Emacs clipboard works out of the box; on terminal Emacs you may need xclip / wl-clipboard (Linux) or clipetty. Evil yank/paste sync with the system clipboard depending on config.

Run doom doctor and M-x doom/profile-startup (or esup). Common causes: unpinned heavy packages, expensive config.el code not deferred, missing native compilation.

emacs --eval '(message "%s" (emacs-init-time))' or use the benchmark-init / esup package. Doom shows init time on the dashboard.

Doom defers package loading until needed. Use after! and use-package! with :defer so your config doesn't load everything at startup.

Runs code only after a package/feature loads, avoiding eager loading:

(after! python
  (setq python-indent-offset 4))

Doom's wrapper over use-package for configuring packages with :hook, :config, :defer, etc., in config.el.

Periodically run doom upgrade, doom doctor, doom purge, and doom sync after config changes. Pin packages if you need stability.

doom clean / doom purge removes build artifacts and elc files; delete ~/.config/emacs/.local/cache for a deeper reset, then doom sync.

A package update introduced an incompatible change. Pin the working version in packages.el with (package! foo :pin "COMMITHASH") and doom sync.

In packages.el:

(package! some-package)

Then doom sync, and configure it in config.el with use-package!.

(package! magit :pin "abc1234...")

Pinning ensures reproducible builds across doom upgrade.

Use after! to re-set variables, add-hook!=/=remove-hook! to change hooks, or advice-add to wrap functions. Avoid editing core module files directly.

A more ergonomic hook adder supporting multiple modes/functions:

(add-hook! 'python-mode-hook #'rainbow-mode)

Sets buffer-local variables via a hook:

(setq-hook! 'python-mode-hook tab-width 4)

Create ~/.config/doom/modules/<category>/<module>/ with config.el, packages.el, init.el, add (:category module) to your doom! block, and doom sync.

Use add-hook 'server-after-make-frame-hook or Doom's after-init-hook=/=doom-after-init-hook for daemon-safe setup (e.g. fonts, themes).

Doom's set-popup-rule! controls popup placement/size:

(set-popup-rule! "^\\*compilation" :side 'bottom :size 0.3)

Doom uses :editor file-templates; add entries to +file-templates-alist or place yasnippet templates so new files autopopulate.

Use feature checks:

(when IS-WINDOWS (setq ...))
(when IS-MAC (setq mac-command-modifier 'meta))

Doom defines IS-WINDOWS, IS-MAC, IS-LINUX.

SPC h f (describe-function), then its name; the help buffer links to source.

SPC h k then press the key (describe-key) shows the bound command and docs.

SPC h b b searches bindings, or M-x describe-bindings lists them all.

SPC h d prefix: SPC h d d docs index, SPC h d m module docs, SPC h d n Doom news, SPC h d h help search.

Run doom doctor, gather the output, and open an issue on the doomemacs GitHub with your Emacs version, OS, and a minimal reproduction.

Run M-x evil-tutor (if installed) or vimtutor; practice text objects and operators daily. SPC h and which-key reinforce keybindings.

The doomemacs GitHub wiki, the official documentation, and many users publish their ~/.doom.d dotfiles on GitHub for reference.

Start Emacs with emacs --debug-init to see the backtrace, or temporarily move the offending file. Fix the elisp error, then restart.

Likely an evil-state or keymap mismatch. Check the state prefix in map! (:n vs :i) and that the target keymap is loaded (wrap in after! if needed).

Network/proxy issues or a bad recipe. Check connectivity, the recipe spelling in packages.el, and run doom sync -u or doom doctor for details.

Terminal Emacs can't render GUI fonts/icons fully; use GUI Emacs or a terminal + Nerd Font, and ensure nerd-icons fonts are installed.

Confirm the language server is installed and on PATH, the +lsp flag is set, :tools lsp is enabled, and check M-x lsp-doctor / *lsp-log* buffer.

You must run doom sync after editing init.el or packages.el, then restart Emacs. config.el changes only need a reload/restart.

Back up ~/.config/doom, delete ~/.config/emacs/.local, run doom sync (and possibly doom install) to rebuild from scratch.

C-g cancels the current command; C-g C-g more forcefully. If truly hung, the daemon may need emacsclient -e '(top-level)' or a process kill as a last resort.