Getting Started with Doom Emacs



Arch Linux

# required dependencies
pacman -S git emacs ripgrep
# optional dependencies
pacman -S fd
yay -S emacs-pdf-tools-git

With Emacs and Doom’s dependencies installed, next is to install Doom Emacs itself:

git clone ~/.emacs.d
~/.emacs.d/bin/doom install


Install the icons to avoid having weird symbols. M-x all-the-icons-install-fonts

Note: M-x is SPC :

Open a file

SPC f f OR SPC .

The bin/doom utility

This utility is your new best friend. It won’t spot you a beer, but it’ll shoulder much of the work associated with managing and maintaining your Doom Emacs configuration, and then some. Not least of which is installation of and updating Doom and your installed packages.

It exposes a variety of commands. bin/doom help will list them all, but here is a summary of the most important ones:

  • doom sync: This synchronizes your config with Doom Emacs. It ensures that needed packages are installed, orphaned packages are removed and necessary metadata correctly generated. Run this whenever you modify your doom! block or packages.el file. You’ll need doom sync -u if you override the recipe of package installed by another module.
  • doom upgrade: Updates Doom Emacs (if available) and all its packages.

doom env: (Re)generates an “envvar file”, which is a snapshot of your shell environment that Doom loads at startup. If your app launcher or OS launches Emacs in the wrong environment you will need this. This is required for GUI Emacs users on MacOS.

  • doom doctor: If Doom misbehaves, the doc will diagnose common issues with your installation, system and environment.
  • doom purge: Over time, the repositories for Doom’s plugins will accumulate. Run this command from time to time to delete old, orphaned packages, and with the -g switch to compact existing package repos.

Use doom help to see an overview of the available commands that doom provides, and doom help COMMAND to display documentation for a particular COMMAND.

I recommend you add a couple of alias to your ZSH configuration.

# Doom Emacs
alias doomsync="$HOME/.emacs.d/bin/doom sync"
alias doomupgrade="$HOME/.emacs.d/bin/doom upgrade"
alias doomdoctor="$HOME/.emacs.d/bin/doom doctor"
alias doompurge="$HOME/.emacs.d/bin/doom purge"
alias doomclean="$HOME/.emacs.d/bin/doom clean"
alias doombuild="$HOME/.emacs.d/bin/doom build"

Doom config file overview

We already know how to open a file and how to use doom utility, so let’s we take a overview for Doom configuration.

Doom Emacs at the least uses three config files.

  • init.el defines which of the existing Doom modules are loaded. A Doom module is a bundle of packages, configuration and commands, organized into a unit that can be toggled easily from this file. You also can design your own Module.
  • packages.el defines which packages should be installed, beyond those that are installed and loaded as part of the enabled modules.
  • config.el contains all custom configuration and code. when you have get so many configuration contains, you may need seperate for each category. There is a example. Click Here

There are other files that can be loaded, but theses are the main ones. The load order of different files is defined depending on the type of session being started.

Config file headers

We start by simply defining the standard headers used by the three files. These headers come from the initial files generated by doom install, and contain either some Emacs-LISP relevant indicators like lexical-binding, or instructions about the contents of the file.

  • init.el
  • packages.el
  • config.el
;;; ../../dotfiles/doom/+research.el -*- lexical-binding: t; -*-

Customized variables

Doom does not recommend the Emacs customize mechanism :

Note: do not use M-x customize or the customize API in general. Doom is designed to be configured programmatically from your config.el, which can conflict with Customize’s way of modifying variables.

All necessary settings are therefore set by hand as part of this configuration file. The only exceptions are “safe variable” and “safe theme” settings, which are automatically saved by Emacs in custom.el, but this is OK as they don’t conflict with anything else from the config.

General configuration

My user information.

(setq user-full-name "Boyang Yan"
      user-mail-address "")

Projects with Projectile, File Explorer with Treemacs & EShell


Doom Emacs have used package Projectile to management our project.

SPC p p - Switch to project. SPC SPC - Find a File in a project

projectile-project-search-path '("~/Project/" "~/dotfiles/" "~/blog/content-org/")


SPC o p - Open When Treemacs is opened, you can type q to close.