What Is Doom Emacs and How to Install It

Doom Emacs is a distribution that aims to create an easy and approachable way to get started with Emacs. Due to hundreds of pages of documentation detailing its various functions. Emacs, by itself, can be daunting.

This is helpful for the already acquainted user and the bookworm. However, this hands-off approach does not help someone that is just interested in trying it out.

Doom Emacs aims to cut the fat and distill the Emacs experience with its core strengths. It allows the user to make use of the extensibility without the need to constantly check a manual just to do basic things. This results in a version of Emacs that can easily be changed and modified to suit the user’s needs.

Installing Doom Emacs is relatively simple. All we need beforehand are three things:

A vanilla Emacs 27.1 installation
ripgrep
Git

Content

Installing Emacs and ripgrep
Installing Git
Installing Doom Emacs
Post-Installation Configurations
The Doom Utility: Your Companion in Doom Emacs
Configuring Doom Emacs
How to Install Additional Packages
Frequently Asked Questions

Installing Emacs and ripgrep

Emacs and ripgrep are available in almost every repository of major Linux distributions. For example, to install Emacs and ripgrep in Debian and Ubuntu 21.10 you can use apt:

sudo apt install emacs-gtk ripgrep

For Arch Linux, use pacman:

sudo pacman -Syu emacs ripgrep

In Fedora, use dnf:

sudo dnf install emacs ripgrep

For Void Linux, use xbps:

sudo xbps-install emacs-gtk2 ripgrep

In my case, I am installing Emacs and ripgrep in my Void Linux system.

It’s important to note that Emacs comes in a variety of flavors. For the most part, the package manager chooses the appropriate version of Emacs to install, but there are rare instances when this process fails.

Therefore, we should be aware of the version that we install. We are looking to install a version of Emacs that can run in a graphical environment, leaving us with:

X11
GTK-2
GTK-3

After that, we can proceed with the installation of Git.

Installing Git

To install Doom Emacs, we need to get a remote code repository from the internet. To do this, install Git. It allows us to instantly copy the code and, more importantly, update between major versions.

Similar to Emacs, Git is common to every Linux distribution. To install it in Debian and Ubuntu, use apt:

sudo apt install git

For Arch Linux, use pacman:

sudo pacman -Syu git

For Fedora, use dnf:

sudo dnf install git

In Void Linux, use xbps:

sudo xbps-install git

In my case, I am installing Git in Void Linux.

Installing Doom Emacs

To install Doom Emacs, we only need to run a few commands:

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

This is a Git command that fetches the Doom Emacs repository for our machine.

The clone function means that we are copying the latest repository when we run the command.
The depth option then truncates the history of the repository to the two most recent versions of the repository.

In this command, we are also saving the repository in the default Emacs configuration directory. Because of that, we need to make sure the directory does not exist by typing this command:

rm -rf /home/$USER/.emacs.d/

After that, we need to start the installation. We do this by typing the following command:

/home/$USER/.emacs.d/bin/doom install

This command installs Doom Emacs on top of the Emacs installation.

Post-Installation Configurations

After that, there are a few more things we need to do to make sure our installation will not run into any issues.

First, set up the PATH variable to detect the “/home/$USER/.emacs.d/doom/bin/” directory. Do this by adding the following line to the “/home/$USER/.profile” file:

export PATH=$PATH:$HOME/.emacs.d/doom/bin

This will update the PATH variable to include the bin directory for Doom. After that, we only need to log back in to reload the environment variable.

To test whether the PATH variable detects the “/home/$USER/.emacs.d/doom/bin” directory, we need to run the command:

doom doctor

This ensures that the installation was done properly. If there are any issues during the process, the doom doctor function will tell us.

The Doom Utility: Your Companion in Doom Emacs

The doom doctor is just one of the available functions in the doom utility. It is the main program that allows us to modify, update and repair Doom Emacs.

As such, the most common functions to be aware of are:

doom doctor will check for any inconsistencies with our initial installation. It is also especially useful when we run into problems while using Doom Emacs. It will check all of the Doom-related directories and configurations for potential errors.
doom upgrade allows us to painlessly upgrade our installation. It will check for any updates in the repository and synchronize our copy with the latest one and handles the migration between versions. To do that, doom upgrade cleans our current Doom configurations and stages the upgrade.
doom purge deals with old packages and modules that were installed in our installation. As such, if we have removed a bunch of packages, it will remove all the unused dependencies. It also has the ability to compress the existing repositories by running it with the -g flag.
doom sync allows us to fix our custom configurations. When we installed Doom Emacs, it created a separate file for personal configurations under “/home/$USER/.doom.d/”. Running the sync function will enable the configurations that were made to .emacs.d in the .doom.d directory.

Configuring Doom Emacs

The .doom.d directory is where all of the Doom configurations live. It consists of three files:

The packages.el file tells what packages to install and from where.
The config.el file is where we our custom configurations are included. This includes the configurations for both Doom and the additional packages that were installed.
The init.el file is the meat and potatoes of Doom Emacs. This is where all of the distribution’s features can be enabled or disabled.

Doom Modules

Doom Emacs allows you the choice of more than 150 modules. We can, then, enable those modules by just picking the ones that we want. This allows us to customize Doom to be our own computing environment.

Adding and removing modules from Doom Emacs is just a matter of modifying the doom! function in the “.doom.d/init.el” file. The general syntax looks something like this:

(doom! :checkers
       (syntax)
       :editor
       (evil)
       :lang
       (org +journal))

To enable a module, we need to label the category. In this example, to add the syntax module, we need to first add the checkers category.

Further, these modules also contain flags that can be activated for a specific module. This is similar to Gentoo’s USE flags that allow you can fine-tune a program by enabling only the features you want.

To add a flag for a module, add a “+” sign followed by the flag name. In this example, we have added the journal flag to org to enable journal support.

Once done, run doom sync to re-initialize Doom Emacs with the settings.

How to Install Additional Packages

By default, Doom Emacs already comes with a multiple packages on installation. Despite that, we can just as easily install additional software from repositories. We can do that by using the package! function in the “.doom.d/packages.el” file.

There a number of ways to install a package in Doom. The most common way is to source the package from ELPA and MELPA. To do that, we only need to add this Lisp code to packages.el:

(package! name-of-package)

This will tell the package! function to check every common repository for the package that we have indicated.

However, if your package does not exist in any repository for Emacs, you can also install it directly from its git repository:

(package! name-of-git-package
          :recipe (:host github :repo "username/package")

This will tell the package! function to pull that specific package from github under the “username/package” repository.

We can also be particular with where in the remote repository we want to pull the package. For example, we can pull a package from a specific place in a repository:

(package! another-git-package
          :recipe (:host github :repo "username/package"
                        :files ("package.el" "path/of/*.el")))

This is useful when we are installing from a repository with a lot of packages sorted in subdirectories. Using this, we can specify what we want to install as a package.

Once done, we need to run doom sync to re-initialize Doom Emacs.

Congratulations! You now have a basic installation of Doom Emacs as well as a basic understanding of how it works and how to configure and extend it. If you are looking for some productivity applications in Linux, we have just the article for you.

Frequently Asked Questions

1. I’ve just installed Doom Emacs, and it only shows a blank screen when I open it.

This is most probably because there is an issue in your .doom.d directory, and Doom Emacs can’t load any of the settings. One way to solve this is to check whether the .doom.d directory exists and that the three files – init.el, packages.el and config.el – exist.

This can also happen because the init.el file that was generated was malformed or did not have doom’s function inside. To fix that, you have to create a doom’s function block with the modules you want to run with Doom Emacs.

2. I’m using package.el to manage my packages, can I still use this in Doom Emacs?

No. Doom Emacs is using a different manager to maintain its packages. You will need to use the package’s function provided by Doom Emacs to install additional software.