wiki | screenshots | faq | troubleshooting

Quick start

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

Doom supports Emacs 25.3 and newer, but Emacs 26.1 is recommended. Doom works best on Linux & MacOS. Your mileage may vary on Windows.

What is Doom Emacs
- Doom's mantras
- Feature highlights
Getting Help
Contributing

What is Doom Emacs

It is a story as old as time. A stubborn, shell-dwelling, and melodramatic vimmer -- envious of the features of modern text editors -- spirals into despair before succumbing to the dark side. This is his config.

Doom is a configuration for GNU Emacs. It can be used as framework for your own configuration, or as a resource for fellow Emacs enthusiasts who want to learn more about our favorite OS.

Doom's mantras

Gotta go fast. Startup and runtime speed are high priorities; many expensive, heavy-handed features and packages have been fine-tuned to that end.
Hacker-friendly. Doom caters to the command line denizen unafraid of writing a little (or a lot of) code to tailor their editor. It also inherits your shell configuration, warts 'n all, and expects frequent trips into the terminal to manage Doom with its bin/doom utility.
Opinionated, but not stubborn. Doom has many opinions spread out across its 120+ modules designed to iron out idiosynchrosies and provide a better and more consistent baseline experience of Emacs and its plugins. However, they mustn't ever compromise your ability to change, rewrite or disable any or all of it, if you ask nicely.
Written to be read. Doom's source ought to be self documenting and easy to grok. Modules should be syntactically sweet and concise, and backend logic should be explicit and abstraction-light. Where complexity arises, comments and documentation shouldn't be far away.

Feature Highlights

A declarative package management system with a command line interface that combines package.el, [use-package] and [quelpa], allowing you to install packages from anywhere.
A popup management system with customizable rules to dictate how temporary/disposable buffers are displayed.
A vim-centric (and optional) experience with evil-mode, including ports of several popular vim plugins, C-x omnicompletion and a slew of custom ex commands.
A Spacemacs-esque keybinding scheme, centered around leader and localleader prefix keys (SPC and SPCm, by default).
Indentation detection and optional integration with editorconfig. Let someone else argue about tabs vs spaces.
Code completion for many languages, powered by company-mode (some may have external dependencies).
Project-awareness powered by projectile, with tools and an API to navigate and manage projects, as well as project/framework-specific minor modes and snippets libraries (and the ability to define your own).
Project search (and replace) utilities, powered by [the_silver_searcher][url:ag], [ripgrep][url:rg], git-grep and wgrep, with integration for ivy (the default) and helm.
Isolated and persistent workspaces powered by persp-mode. Also substitutes as vim tabs.
Inline/live code evaluation (using quickrun), with REPL support for a variety of languages.
A jump-to-definition/references implementation for all languages that tries to "just work," resorting to mode-specific functionality, before falling back on [dump-jump][url:dumb-jump].

Troubleshooting

Encountered strange behavior or an error? Here are some things to try before you shoot off that bug report:

Run bin/doom refresh. This ensures Doom is properly set up and its autoloads files are up-to-date.
If you have byte-compiled your config (with bin/doom compile), see if bin/doom clean makes your issue go away. Never debug issues with a byte-compiled config, it will only make your job harder.
Run bin/doom doctor to detect common issues in your development environment.
Search Doom's issue tracker for mention of any error messages you've received.
Visit our FAQ to see if your issue is listed.

If all else fails, file that bug report! Please include the behavior you've observed, the behavior you expected, and any error message in the *Messages* buffer (can be opened with SPC h m or M-x view-echo-area-messages). It'd be a great help if you included a backtrace with them as well.

We've also got a Discord server. Hop on! We can help!

Contributing

Doom (and my Emacs work in general) is a labor of love and incurable madness, done on my spare time. If you'd like to support my work, I welcome contributions:

I love pull requests and bug reports. Check out the [Contributing Guidelines][docs:contributing] (WIP) to find out how you can help out.
I welcome Elisp pointers! Don't hesitate to tell me my Elisp-fu sucks (but please tell me why).
Hop on our Discord server and say hi! Help others out, hang out or talk to me about Emacs, or gamedev, or programming, machine learning, physics, pixel art, anime, gaming -- anything you like. Nourish this lonely soul!
If you'd like to support my work financially, consider buying me a drink through liberapay or paypal. Donations are a great help. My work here contends with full-time studies, my ventures in indie gamedev, and my freelance work.