Install and Configure Doom Emacs

Cover Image for Install and Configure Doom Emacs
Lauro Silva

Doom Emacs is a framework that’s built for GNU Emacs (vanilla Emacs). Doom Emacs provides reasonable defaults and curated opinions, and it has a great modern UI.

This tutorial will show you how to install Doom Emacs on macOS.

Prerequisites

There are no perquisites. The goal of this tutorial is to be accessible to beginners. It does not make assumptions, and it strives to explain all the jargon.

Goal

  • Install Doom Emacs on macOS.
  • Understand Doom Emacs vs Emacs
  • Learn to manage and maintain your Doom Emacs configuration

Xcode

First, installed Xcode. Download and install it from the App Store or from Apple’s website. Once you have installed Xcode, you will need to install the Xcode command-line tools:

sudo xcode-select –install

It’ll prompt you to install the command-line tools. Follow the instructions and you’ll have Xcode and Xcode command line tools both installed.

Homebrew

You will use Homebrew to install packages. Run the following in a terminal, hit Enter, and follow the steps on the screen.

/bin/bash -c “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)”

To install a package (or Formula in Homebrew vocabulary) simply type:

brew install {name of the package}

Dependencies

Before installing Doom Emacs, make sure you have the following packages installed. If not, installed them using Homebrew:

brew install git ripgrep fd coreutils

  • git - version control
  • ripgrep - recursively searches directories for a regex pattern
  • fd - improves file indexing performance for some commands
  • coreutils - contains many tools, including date, cat

Emacs Plus

Before you install Doom Emacs, you need to install Emacs Plus. Emacs Plus comes with stander defaults and leaves out controversial options as opt-in.

The first step is to add an additional repository to the list of formulas that Homebrew tracks:

brew tap d12frosted/emacs-plus

By default, it tracks a GitHub repository, in this case: d12frosted/emacs-plus.

Doom Emacs recommends installing Emacs 27. Since it is already being tracked in Homebrew, we can install it with the following command:

brew install emacs-plus@27 –with-modern-black-variant-icon

  • emacs-plus@27 - installs emacs-plus specifying version 27.
  • –with-modern-black-variant-icon - This adds a nice icon. Feel free to pick a different icon from this list.

Doom Emacs

Finally, this is the part where you will install Doom Emacs. Git clone the Doom Emacs repository into .emacs.d, a config file provided by Emacs Plus:

git clone https://github.com/hlissner/doom-emacs ~/.emacs.d

Let’s move into the .emacs.d directory. It will be located in your home directory.

cd ~ cd .emacs.d

Doom is constantly being develop, to stay up to date make sure you are using the develop branch.

git checkout develop

Doom Utility

Doom comes with a command-line tool, you will use it to manage and maintain your Doom Emacs configuration. From inside the .emacs.d directory, it is located under bin.

Move into the bin directory and execute the following command to install Doom Emacs:

doom install

You will also have access to the other commands, such as:

# synchronizes your config with Doom Emacs doom sync # Updates Doom Emacs and all its packages doom upgrade # regenerates envvar file doom env #diagnose issues with your installation, system, and environment doom doctor # delete old packages doom purge

Finally, run emacs from the terminal and you should now see the doom homepage. Yay! You can now access Doom’s documentation from within Emacs via ‘SPC h d h’ or ‘C-h d h’ (or ‘M-x doom/help’).

Configure

Doom Emacs is constantly being developed and it is recommended to keep costume configuration separate, this is the purpose of .doom.d.

The .doom.d directory was created when installing Doom Emacs, it contains 3 private files:

  • config.el - it’s empathy, you add your custom configuring here
  • init.el - this is were you select and enable packages
  • packages.el - stores which packages you want to install ontop of packages that have already been installed

From within doom, you can select these private files by pressing SPC f p.

Don’t forget to run doom sync, then restart Emacs, after modifying:

~/.doom.d/init.el or ~/.doom.d/packages.el.

The doom sync command installs needed packages, removes unused packages.

Good Practices

It is recommended that .doom.d is kept under version control. Part of the ethos of the Emacs is sharing your config files. I've uploaded my config files, you can take a look at them here: https://github.com/laurosilvacom/.doom.d

You’ll also be using the Doom utility command-line tool. It is recommended that you alias these command in .zshrc or .bash_profile:

alias doomsync=“~/.emacs.d/bin/doom sync” 
alias doomdoctor=“~/.emacs.d/bin/doom doctor” 
alias doomupgrade=“~/.emacs.d/bin/doom upgrade” 
alias doompurge=“~/.emacs.d/bin/doom purge”

Once you have added these alias, reload .zshrc or .bash_profile and one of the commands from any directory.

Summary

Having Doom Emacs up and running is the biggest obstacle when learning Emacs. This tutorial showed you how to install Homebrew, Homebrew packages, Emacs Plus, Doom Emacs, and good practices when using the Doom Utility.

There is much more to learn and do with Emacs, but I hope you feel confident to dive-in and play around with Emacs yourself now.

Please let me know if anything was unclear, or if there's anything else you'd like to see in this or a subsequent article.