FAQ

A configuration framework built on GNU Emacs that provides curated packages, keybindings, and sane defaults to make Emacs fast and usable out of the box.

Code editing, writing, note-taking with org-mode, project management, and general power-user workflows. It’s highly extensible for almost any text-based task.

No. It has a steep learning curve and assumes Emacs familiarity. Beginners are better off starting with VS Code or Spacemacs first.

Doom Emacs requires GNU Emacs 28 or higher. First install Emacs on your system, then clone the Doom config folder, run the install command from your terminal, and finally add Doom to your system PATH. The full step-by-step walkthrough is available on the Install page of this site.

Yes — if you’re committed to Emacs. The speed, organised module system, and Vim keybindings make it one of the best Emacs setups available.

Doom aggressively lazy-loads packages, defers byte-compilation, caches autoloads, and patches upstream modules to avoid unnecessary startup work. That makes cold starts much faster than hand-rolled Emacs configs with the same feature set.

Yes, but the recommended Windows path is WSL or WSL2 for a real Linux userland. Native Windows Emacs builds are partially supported, while WSL gives the most reliable Doom experience.

Both offer modal editing and strong extensibility. Neovim is lighter and focused on Lua plugins; Doom Emacs brings the broader Emacs ecosystem, Org-mode, Magit, and declarative modules. Choose Doom if you want the power of Emacs with Vim-style bindings.

Both are Emacs distributions with layered configs. Doom emphasizes faster startup, lazy loading, and a slimmer curated core while remaining customizable through init.el, packages.el, and config.el.

LazyVim targets the Neovim ecosystem. Doom Emacs targets GNU Emacs and brings the full Emacs package ecosystem, Org-mode workflow, and native Emacs extensions.

Vanilla Emacs has fewer defaults and a blank starting point. Doom Emacs adds a curated configuration layer, sensible defaults, and a CLI while still running on top of stock GNU Emacs.

Zed is a standalone code editor. Doom Emacs is a framework for GNU Emacs that lets you keep the Emacs runtime and plugin model while layering on Doom’s performance optimizations and modules.

Obsidian is notes-first, standalone software. Doom Emacs is a programmable Emacs environment for coding, note-taking, and productivity all inside one editor.

Doom Emacs is not a fork. It is a structured config and CLI on top of stock GNU Emacs. You keep Emacs packages and upgrade paths while gaining Doom’s module system and performance tuning.

• Not loading — verify stable Emacs, run doom doctor, and use doom sync.
• Icons missing — install recommended fonts and rerun sync.
• Package cl deprecated — update packages and pin the offending package if needed.
• Directory is not a project — open the repository root, add a project marker, or configure your project backend.

Use stable GNU Emacs 29.x or 30.x per the Install page. Disable the evil module in init.el if you want stock Emacs keys.

The Doom CLI lives under ~/.config/emacs/bin. Use doom sync, doom upgrade, and quit Emacs with C-x C-c or :qa in evil.

To evaluate whether Doom is the right choice, our documentation provides four comprehensive sections addressing different perspectives: the rationale behind choosing Emacs, potential drawbacks to consider, advantages specific to Doom, and limitations you might encounter. Additionally, we maintain detailed comparison resources with other popular starter kits to help you make an informed decision.

Doom was developed from the ground up starting in 2013 as a personal learning project for Emacs Lisp and configuration experimentation. While early adopters drew comparisons to other starter kits, the project stands as an independent creation. That said, Doom has incorporated certain concepts that emerged from the broader Emacs ecosystem—such as adopting a leader-key pattern popularized by other projects or accepting community-contributed ideas—but these additions were evaluated on their merit rather than being wholesale adoptions.

The distinction reflects different philosophical approaches to Emacs configuration. While starter kits typically abstract away complexity to deliver ready-to-use functionality, a true framework equips you with enhanced tools, reusable patterns, and organizational methodologies that enable you to build solutions more effectively. Doom's core architecture operates as a framework providing these capabilities, while its collection of modules functions as a starter kit offering. This enables users to leverage the framework's infrastructure while customizing their setup according to their needs.

Henrik serves as the primary author and sole maintainer of this project. While future expansion of the core maintenance team is planned, several prerequisites must be satisfied first: comprehensive technical documentation outlining versioning strategies, community guidelines, and coding standards; expanded test coverage across units, integration points, and package behavior; and resolution of current limitations affecting CLI stability and performance. Additionally, we actively seek maintainers for individual modules to distribute responsibility across the community.

The naming originates from childhood nostalgia—specifically, exposure to id Software's groundbreaking Doom source code in 1999, which sparked an early fascination with programming fundamentals. This formative experience combined with playful irreverence and the notion that Emacs represents a uniquely complex ecosystem resulted in the somewhat tongue-in-cheek "Doom Emacs" designation. The name captures both technical aspiration and humorous self-awareness about Emacs's reputation.

The built-in package.el system has significant limitations when managing sophisticated configurations: it lacks mechanisms to recover from failures, offers no versioning flexibility or rollback capabilities, cannot access alternative repositories for cutting-edge patches, and carries performance overhead during startup. Straight.el addresses these shortcomings by enabling independent version pinning, git-based history exploration, access to diverse package sources, and optimized initialization. While mastering Git provides alternative workarounds, the effort becomes impractical beyond handling a handful of packages.

While rapid startup receives disproportionate attention from users discovering Doom, the project maintains full compatibility with daemon mode and doesn't discourage its use. However, the broader perspective recognizes that requiring daemon mode to achieve acceptable responsiveness reveals a systemic issue within Emacs that extends beyond what optimization can address. Runtime performance represents a more significant concern than cold-start metrics, though improvements in either domain often yield mutual benefits. Current optimization strategies—including daemon mode and native compilation—serve as interim solutions until underlying architectural limitations are resolved.

Development activity and announcements are tracked through our official manual, which maintains current links to all project resources and communication channels where development discussions occur.

Our community maintains multiple platforms for support and discussion. We recommend beginning with our Discourse community, which provides a more structured environment for detailed conversations. Additional resources exist across multiple communication platforms documented in our community guidelines.

There is no formal submission mechanism for FAQ content. Our community leadership team curates entries based on question frequency observed across our GitHub, Discord, and Discourse communities, selecting items that would benefit the broader user base. Participate in these communities with your questions, and frequently-asked topics will naturally emerge as FAQ candidates.

Execute M-x doom/info within Emacs or run doom info from your terminal to generate comprehensive installation details and environmental information. For version-only output, use M-x doom/version or doom version from the command line. Your Doom installation version also displays on the dashboard's mode line.

The recommended approach involves enabling LSP (Language Server Protocol) support through Doom's module system. First, activate the LSP module under development tools. Then, enable the +lsp flag on your desired language module—for instance, add +lsp to the Python module configuration. Install the corresponding language server using your package manager or through Emacs using M-x lsp-install-server. Run doom sync to apply changes and restart Emacs. If Emacs cannot locate the server, run doom env to regenerate your environment variables. Note that certain languages have alternative tooling superior to LSP implementations.

Doom exposes multiple font configuration variables: doom-font for primary text display, doom-variable-pitch-font for proportional typography, doom-emoji-font for emoji rendering, doom-symbol-font for symbol display, doom-big-font for magnified presentation mode, and doom-serif-font for serif typography. Each accepts font specifications using multiple syntaxes: font-spec objects with properties like family and size, XFT font strings in short or long form, or XLFD format strings. Apply changes by selecting configuration statements and evaluating them with M-x eval-region, then reload fonts with M-x doom/reload-font. Font detection issues are typically system configuration problems, not Doom limitations.

Add theme declarations to your configuration file to change themes. Switch themes interactively using the menu system or M-x load-theme. Creating custom themes or modifying existing ones requires consulting our dedicated theming documentation on the community forum.

The recommended method involves running doom upgrade from your terminal followed by restarting Emacs. This represents the most reliable approach. Should this command fail, manual updating involves navigating to ~/.emacs.d, pulling the latest source with git pull, then executing doom sync -u. Always consult doom help upgrade for current procedures, as update processes may evolve.

Emacs provides several binding functions, but Doom simplifies this through the map! macro, offering cleaner syntax than define-key or global-set-key. Access comprehensive examples through f map! or consult configuration examples in Doom's default evil-bindings file. Keybinding complexity in Emacs stems from hierarchical keymap precedence, making thorough understanding essential—see our detailed keybinding documentation for clarification.

Our manual provides detailed guidance on this topic, including techniques for changing leader keys, creating bindings under the leader prefix, and establishing aliases for quick access.

Doom integrates the display-line-numbers package (built into recent Emacs versions). Disable entirely using display-line-numbers-type set to nil, or switch between styles: t for standard numbering, 'relative for vim-style relative numbers, or 'visual for screen-relative counting. Cycle through styles dynamically with M-x doom/toggle-line-numbers (default shortcut: t l). Full documentation accessible through variable documentation utilities.

Disable the Evil module through your configuration. Refer to the module's comprehensive documentation for the specific procedure, accessible through the module help system.

Run doom sync following these actions: manually updating Doom through git pull, modifying your init.el module configuration, editing autoload files in any module directory, updating packages.el declarations, or installing external packages through your system package manager. This command resolves missing dependencies and updates autoload caches. It is unnecessary for changes to config.el files. When troubleshooting unexpected behavior, running doom sync preemptively eliminates many common issues.

Most Doom commands support -! or --force flags that globally suppress interactive confirmation prompts.

Your configuration directory ($DOOMDIR) transfers safely across systems; however, the Emacs installation directory ($EMACSDIR) does not. Packages contain system-specific paths and compiled code sensitive to Emacs versions and operating systems. After transferring your config, execute doom sync on the destination system to properly resolve dependencies and regenerate necessary files. Transferring compiled packages across different environments typically causes failures.

Remove the directory ~/.emacs.d/.local/straight and execute doom sync to reinitialize all packages and configurations to their default state.

By default, Doom remaps s and S keys to the evil-snipe plugin, providing two-character motion capabilities similar to vim-seek. This replaces traditional substitute functionality in favor of more powerful motions. To restore original Vim behavior, disable evil-snipe-mode by removing it from the initialization hooks.

Performance optimization strategies evolve with each Emacs release, and solutions vary accordingly. We maintain current guidance on our community discussion platform that reflects latest findings and recommendations rather than static documentation.

The most common cause is a ~/.emacs configuration file, which Emacs prefers over the ~/.emacs.d directory, bypassing Doom entirely. If this doesn't apply, run doom doctor to identify potential configuration issues and receive diagnostic suggestions.

Common causes include: an unreachable private configuration directory (check that only one of ~/.doom.d or ~/.config/doom exists with a proper init.el), a startup error preventing dashboard initialization (inspect logs with C-h e for error messages), or the dashboard module being disabled (verify module status in your configuration). Running doom doctor can detect many such issues and provide guidance.

Three primary causes affect program discovery: incorrectly configured shell initialization (verify with which in your shell), app launchers using wrong shell environments (common with custom launchers), or macOS GUI app isolation (affects Emacs.app bundles). Once shell configuration is correct, generate an environment file with doom env, which Doom loads at startup. For launcher-related issues, consult your launcher documentation or community support channels.

Several factors prevent configuration updates: dual configuration directories (Doom prioritizes ~/.config/doom over ~/.doom.d), forgetting to run doom sync for structural changes, or loading packages before their initialization. Use with-eval-after-load to defer configuration until packages load. Notable exceptions exist for file paths and variables requiring pre-load setup. Run doom doctor to detect issues or seek community support.

Common culprits include: fonts lacking glyph support (experiment with alternative fonts), ligature rendering issues (try disabling the ligatures module), or system-specific problems with fringe/margin manipulation particularly on macOS. No reliable fix exists for the latter without reinstalling Emacs or disabling problematic modules like doom-dashboard or magit. Troubleshooting guides in our documentation address hard crashes and freezes specifically.

The Emacs wiki maintains solutions for TRAMP connectivity issues specific to various configurations.

Doom highlights non-conforming indentation—mixing spaces and tabs differently than your declared style. Fix indentation directly using M-x tabify or M-x untabify, configure indent-tabs-mode in your setup, employ EditorConfig for project-specific standards, or leverage dtrt-indent for automatic detection.

Windows permission issues require adjusting ownership of ~/.emacs.d/server. Right-click the directory, access Properties, navigate to Security settings, modify the Owner field to your account username.

Emacs's hierarchical keymap system means other keymaps may override your bindings. For example, mode-specific maps take precedence over global maps. Inspect conflicting bindings with C-h k and unbind them from their keymap before rebinding globally. The map! macro documentation provides examples of handling this complexity.

Three primary causes exist: missing GNU tar/gzip tools (particularly on macOS/BSD where BSD versions are defaults), tar/gzip not in shell PATH (run doom env to regenerate environment after fixing shell configuration), or using unsupported Emacs distributions (consult our manual for recommended Emacs sources). File a bug report if none of these resolve the issue.

Our contributor manual outlines numerous contribution opportunities beyond code submissions, allowing various skill levels to support the project's growth and sustainability.

Verify no duplicate PRs exist for your issue. Include clear explanations of why changes are needed and what problems they solve. Follow established git commit conventions and code style guidelines. Keep changes focused and targeted. Ensure you've targeted the master branch. For new tools or packages, provide setup instructions or example configurations. Include shell.nix or Dockerfile references when applicable. These practices reduce review time significantly.

Approvals often precede merges by days to allow testing, regression detection, and time for corrections. After approval, await maintainer availability for merging. If delays exceed a week, respectfully request status updates through issue comments or community channels.

Emacs's inherent complexity generates many false-positive, redundant, or vague issues that burden our tracker. Limited maintenance resources require strict prioritization of actionable, reproducible issues with clear investigation paths. Issues violating these standards receive brief explanations and closure procedures for reversal if mistaken. Examples include unverifiable performance problems, behavior reproducible only in modified configurations, vanilla Emacs issues, vague improvement requests, missing information, usage questions (belonging in support channels), unfocused multi-part issues, or hostile interactions.

#'symbol abbreviates (function symbol), similar to how 'symbol abbreviates (quote symbol). This syntax signals the byte-compiler to treat symbols as functions and perform compile-time validation. At runtime, #'symbol and 'symbol behave identically—the distinction exists purely for compile-time checking and documentation clarity.

Doom documentation on this topic remains in development. However, our community platform contains detailed articles explaining current and historical optimization techniques implemented throughout the project.

This topic is currently being developed with comprehensive documentation to follow.

Built-in Emacs modules (subr-x, seq, map, pcase, cl-lib) available since version 27.1—which is Doom's minimum—provide functionality that previously required external libraries. Preferring native functionality reduces dependencies while maintaining compatibility. Many third-party packages still require these libraries, so installation is common.

Customize bypasses normal load order, complicating integration in frameworks. It creates dual configuration sources that override each other unpredictably. While helpful initially, learning Emacs Lisp directly enables full extensibility. Customize's functionality overlaps with built-in documentation and inspection commands. Finally, abandoning Customize becomes necessary for any configuration complexity. Doom emphasizes facing Emacs Lisp rather than circumventing it, believing this better serves users long-term.

Evil's built-in text objects (i, o, a, b, x) and motions provide more precise and consistent selection than expand-region's approach. Evil selects exactly what you need from the start, whereas expand-region requires iterative adjustment. Evil users benefit more from mastering text object combinatorics than from expansion/contraction commands.

exec-path-from-shell spawns shell processes at startup, which can be slow and unreliable with non-standard shells. It uses a whitelist approach, capturing only selected variables. doom env pre-generates environment variables using a blacklist approach, capturing your entire environment. This front-loads debugging while avoiding startup delays. If you prefer exec-path-from-shell, it's trivial to install manually.

ws-butler only cleans whitespace on lines you've modified, preventing unnecessary changes to unrelated code. Automatic full-buffer cleanup tools introduce unrelated modifications that burden reviewers and distract from actual changes. ws-butler respects teammate workflows while maintaining code cleanliness.

Consider becoming a GitHub sponsor, which directly supports project development. Alternative sponsorship methods are documented on the maintainer's profile. Sponsoring translates directly into increased development time on Doom and related open-source initiatives.

After sponsoring, you'll receive automated instructions. Alternatively, email contact@henrik.io or message on Discord with your GitHub username and optionally your Discourse username to claim rewards.

Becoming a module maintainer, community moderator, or recognized community regular provides equivalent benefits to the $25/month sponsor tier. Module maintainers shepherd specific Doom modules and serve as technical consultants for their ecosystems. Moderators steward GitHub, Discord, and Discourse communities. Regulars are active, helpful community pillars. These roles offer sponsorship-equivalent perks while providing direct project contribution.

"First shake" means issues receive initial triage and investigation before others, with single-sitting resolution when possible. "First priority" means complete issue resolution before addressing anything else. Exceptions exist for extraordinarily complex issues, outside expertise, or dependent efforts. Users depending on Doom for professional work benefit most from first priority support.