Skip to content
Get packs

Guide · Open source

How to use Doom Emacs core: install, sync and run it

Updated · written with AI from the project's own documentation and checked against our catalogue data

Doom Emacs is a configuration framework for GNU Emacs that supplies reasonable defaults, optional modules for many languages and tools, and a command line script called bin/doom for installing and updating packages. This guide shows you how to check prerequisites, install Doom from the README commands, and use the core commands you will need day to day. By the end you will have Doom installed and know which commands to run after changing your config.

Doom Emacsdoomemacs/core · ★ 22.8k · MIT

Quick start

  1. 1Check prerequisites. Confirm you have GNU Emacs 27.1 to 31.1, Git 2.23 or newer, and ripgrep 11.0 or newer installed.
  2. 2Clone the repository. Run git clone --depth 1 https://github.com/doomemacs/core ~/.config/emacs to download Doom into your Emacs config directory.
  3. 3Install Doom. Run ~/.config/emacs/bin/doom install to set Doom up.
  4. 4Add bin to your PATH. Add ~/.config/emacs/bin to your PATH so the doom command is available everywhere.
  5. 5Sync after config changes. Run doom sync after editing init.el or packages.el to install missing packages and regenerate caches.
  6. 6Check for problems. Run doom doctor to find missing dependencies or config mistakes.

Check the prerequisites before you install

Doom needs GNU Emacs 27.1 to 31.1, with 31.1 recommended. Using only Doom's command line requires 27.1 or newer, while using Doom as a starter kit requires 29.1 or newer.

You also need Git 2.23 or newer and ripgrep 11.0 or newer. Fd 7.3.0 or newer is optional but recommended for faster file indexing.

  • GNU Emacs 27.1 to 31.1 (31.1 recommended)
  • Git 2.23 or newer
  • ripgrep 11.0 or newer
  • Optional: fd 7.3.0 or newer, GNU versions of find, ls and tar on macOS and BSD, and the Symbola font

Install Doom Emacs with clone and build

Doom is installed by cloning the repository into your Emacs config directory and then running its install script. The README gives these two commands.

After installing, the README suggests adding ~/.config/emacs/bin to your PATH so you can run doom from anywhere. It then points you to the Getting Started guide for configuring and maintaining Doom.

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

Keep Doom in sync with your private config

Run doom sync whenever you modify your private init.el or packages.el. It installs missing packages, removes orphaned packages and regenerates caches. It is also needed after you install or remove an Emacs package through your OS package manager, such as mu4e or agda.

To include a snapshot of your shell environment that Doom loads at startup, use doom sync --env. The README says this lets Emacs inherit your PATH and replaces exec-path-from-shell.

  • doom sync: install missing packages, remove orphaned ones, regenerate caches
  • doom sync --env: load a snapshot of your shell environment at startup
doom sync doom sync --env

Update Doom and diagnose problems

Use doom upgrade to update Doom to the latest release and all installed packages. When something is wrong, run doom doctor. Doom does not automatically install system dependencies, so doctor is how you find what is missing on your system.

Doom has around 150 optional modules, some with their own dependencies. The README suggests checking their documentation or running doom doctor to catch anything you missed.

  • doom upgrade: update Doom and installed packages
  • doom doctor: diagnose common system and config issues
doom upgrade doom doctor

Know what Doom gives you and what it expects

Doom's features include curated defaults, a modular structure for separating config concerns, and a declarative package management system powered by straight.el. Optional vim emulation comes through evil-mode, and LSP support is opt-in via lsp-mode or eglot.

Doom assumes you are comfortable with Emacs concepts. It also adds its own conventions on top of vanilla Emacs, so expect a learning curve even with the defaults.

  • Optional vim emulation through evil-mode
  • Opt-in LSP integration using lsp-mode or eglot
  • Project search with ripgrep and ivy or helm
  • Isolated, persistent workspaces that act like vim tabs

What people use it for

  • Starting from a curated Emacs setup instead of writing an init file from scratch.
  • Adding vim-style editing through optional evil-mode support.
  • Working across many languages with opt-in modules for syntax highlighting, linters and REPLs.
  • Pinning Emacs packages to specific commits through the declarative package system.
  • Loading your shell PATH into Emacs with doom sync --env.

Frequently asked questions

Is Doom Emacs free to use?

Doom Emacs is released under the MIT licence, as listed on its repository page. The MIT licence allows you to use, modify and share the code under its terms.

What Emacs version does Doom Emacs need?

Doom supports GNU Emacs 27.1 to 31.1, and the README recommends 31.1. Using Doom as a starter kit requires 29.1 or newer.

Why does doom doctor report missing dependencies?

Doom does not automatically install system dependencies, so it relies on doom doctor to show what is missing. Run the command and install the items it lists.

Can I use Doom Emacs with unstable Emacs builds?

The README warns against unstable and pre-release builds, which end in numbers like .50, .60 or .9X. It says support lags behind the bleeding edge by at least a month or so.

What is the difference between Doom Emacs and Spacemacs?

Both are configuration frameworks for Emacs, and Spacemacs is listed as a comparable project. This page does not compare them in detail, so check each project's documentation to decide which fits your workflow.

Does Doom Emacs work without any configuration?

No. The project is aimed at people familiar with Emacs concepts, and it adds its own conventions to vanilla Emacs. Expect a learning curve even though the defaults are curated.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Doom Emacs suits Emacs users who want a curated, fast-starting base, Vim users who want evil-mode, and developers who want opt-in language support. People who want zero configuration, or full control over a minimal config, should look at a simpler setup or a comparable project such as Prelude or Centaur Emacs.

Install options & downloads