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.
By the way, download our Emacs keyboard shortcuts cheatsheet to increase your productivity.
Installing Doom Emacs is relatively simple. All we need beforehand are three things:
- A vanilla Emacs 27.1 installation
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
sudo apt install emacs-gtk ripgrep
For Arch Linux, use
sudo pacman -Syu emacs ripgrep
In Fedora, use
sudo dnf install emacs ripgrep
For Void Linux, use
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:
After that, we can proceed with the installation of 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
sudo apt install git
For Arch Linux, use
sudo pacman -Syu git
For Fedora, use
sudo dnf install git
In Void Linux, use
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.
clonefunction means that we are copying the latest repository when we run the command.
depthoption 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:
This command installs Doom Emacs on top of the Emacs installation.
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:
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:
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 doctorwill 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 upgradeallows 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 purgedeals 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 syncallows 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 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.
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.
3. I’ve installed this package in Doom Emacs and don’t want it anymore. How can I uninstall it?
Removing a package in Doom Emacs is relatively trivial. You only need to run this piece of Lisp code in your .doom.d/packages.el:
(package! some-package :disable t)
After that, you need to run doom sync to reload Doom Emacs. When you log back in, that package will be uninstalled.
Our latest tutorials delivered straight to your inbox