Skip to content

Getting Started

Henrik Lissner edited this page Dec 5, 2018 · 9 revisions


To use Doom you need Emacs 25.3+ (26.1 is recommended), Doom itself cloned to ~/.emacs.d, its plugins installed, and any further dependencies for modules installed on your system.


Doom requires Emacs 25.1 or above. There are many ways to install Emacs, depending on your OS:

  • On Linux, Emacs ought to be available through your distro’s package manager:
    • Arch Linux: pacman -S emacs or pacaur -S emacs-git
    • Ubuntu:
      sudo add-apt-repository ppa:kelleyk/emacs
      sudo apt-get update
      sudo apt-get install emacs25
  • On MacOS, I recommend homebrew and the emacs-plus recipe:
    brew tap d12frosted/emacs-plus
    brew install emacs-plus
    ln -s /usr/local/opt/emacs-plus/ /Applications/

    Alternatively, you can use the emacs recipe:

    brew install emacs --with-cocoa --with-gnutls
  • On Windows: *Doom doesn’t officially support Windows,* so your mileage there may vary. Some have reported success using the WSL, however.

Alternatively, build Emacs from source.


The bare minimum you need to get Doom going is:

git clone -b develop ~/.emacs.d
~/.emacs.d/bin/doom quickstart

Post-installation tips

  • I recommend you add ~/.emacs.d/bin to your PATH, to make the ~/.emacs.d/bin/doom utility easier to access.
  • If something goes wrong, run doom doctor and see if it can tell you what’s wrong.
  • GUI Emacs users must install the icon fonts included in the all-the-icons packages, or you’ll see mismatched/odd unicode symbols lying around. Run M-x all-the-icons-install-fonts from inside Emacs to do so.
  • It is vital that you run doom refresh on the command line whenever you:
    • Modify your doom! block (in ~/.doom.d/init.el),
    • Modify any module’s packages.el file,
    • Modify any module’s autoload files,
    • Or update Doom from upstream.

IMPORTANT: Once byte-compiled, changes to your config won’t take effect until you recompile (doom recompile) or get rid of byte-compilation entirely (doom clean), then restart Emacs.

Extra dependencies

Doom’s modules may have dependencies that are needed for certain features to work (like auto-completion or syntax checking). Doom should work without them, but will be crippled (you will receive warnings).

All but the simplest modules should have a file that cover extra setup in detail, if any. Use M-x doom/describe-module to quickly jump to them.


From time to time you should update Doom and its packages. Doom is constantly worked on.


Run doom update to update your plugins. If you’d like to skip the confirmation prompt (e.g. for integration into shell scripts), use the -y flag: doom -y update.


Updating Doom from upstream is straight-forward, assuming you haven’t made any changes to core Doom files.

# If you cloned directly from hlissner/doom-emacs
doom upgrade   # or doom up

# If you prefer to pull manually...
git pull 
doom refresh   # or doom re

# If you cloned from a fork of doom-emacs
git remote add upstream
git pull upstream develop
doom refresh

These are the simplest & recommended approaches.

Clone this wiki locally
You can’t perform that action at this time.