Skip to content

Getting Started

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

Install

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.

Emacs

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/Emacs.app /Applications/Emacs.app
        

    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.

Doom

The bare minimum you need to get Doom going is:

git clone -b develop https://github.com/hlissner/doom-emacs ~/.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 README.org file that cover extra setup in detail, if any. Use M-x doom/describe-module to quickly jump to them.

Update

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

Packages

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.

Doom

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 https://github.com/hlissner/doom-emacs
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.