Docs

Configure Doom Emacs Your Way

Doom Emacs is designed to be configured programmatically. All your personal settings live in three simple files inside a single folder. This guide explains each file, what it does, and how to use it correctly.

Your Config Directory

All personal settings live in a folder called $DOOMDIR. By default this is located at ~/.config/doom/.

Inside this folder you will find three core files:

File Path Purpose
init.el ~/.config/doom/ Enable or disable modules
config.el ~/.config/doom/ Personal settings and customisations
packages.el ~/.config/doom/ Install extra packages

Some setups still use ~/.doom.d/; either location can act as $DOOMDIR depending on your install.

The Three Core Files

File 1 — init.el

This file controls which Doom modules are active. It is loaded very early during startup before anything else. This is where your doom! block lives.

  • Add or remove modules from categories like :completion, :editor, :lang, :ui
  • After any change you must run doom sync and restart Emacs
  • Do not put general config code here — only module toggles
  • Modules can have optional flags using the + symbol (e.g. python +lsp)

Example:

(doom!
 :completion
 vertico

 :editor
 evil
 snippets

 :lang
 python
 javascript
 org

 :ui
 doom
 modeline)

File 2 — config.el

This is your main personal configuration file. It loads after all modules and is where 99% of your customisation goes.

  • Set your name, email, font, and colour theme
  • Customise individual module behaviour
  • Add hooks, keybindings, and overrides
  • Use after! to configure packages safely after they load
  • Do not use M-x customize — it conflicts with Doom's config system

Example:

(setq user-full-name "Your Name"
      user-mail-address "you@email.com")

(setq doom-theme 'doom-one)
(setq doom-font (font-spec :family "Fira Code" :size 14))
(setq org-directory "~/org/")

File 3 — packages.el

Declare any extra packages not part of a Doom module. Doom uses straight.el instead of the built-in package.el.

  • Install from MELPA, ELPA, or directly from a Git forge via recipes
  • Use package! to declare a new package
  • Use :disable t to turn off a default Doom package
  • Always run doom sync after changes

Example:

;; Install from MELPA
(package! some-package)

;; Install from a Git forge (straight.el recipe)
(package! some-package
  :recipe (:host git :repo "username/repo"))

;; Disable a Doom default package
(package! evil-snipe :disable t)

Essential CLI Commands

After editing your config files, use these commands in the terminal to apply changes:

Command What It Does
doom sync Apply changes after editing init.el or packages.el
doom upgrade Update Doom Emacs and all installed packages
doom doctor Diagnose issues with your setup and environment
doom env Refresh your shell environment snapshot
doom gc Clean up old and orphaned packages

Common Configuration Tasks

The most frequent things people add to config.el. Each example can be copied directly into your config.el file.

Changing Your Theme

(setq doom-theme 'doom-dracula)

Changing Font Size

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

Setting Line Numbers

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

Disabling a Module Flag

;; In init.el
(python +lsp)   ; with LSP support
python          ; without LSP support

Common Mistakes to Avoid

  • Do not use M-x customize — it conflicts with Doom's config system
  • Do not add general settings to init.el — use config.el instead
  • Do not use use-package without :defer or :after — breaks startup speed
  • Always run doom sync after editing init.el or packages.el
  • Always restart Emacs after doom sync for changes to take effect
  • Do not install packages via package-install — use packages.el instead