Repository files navigation

• Introduction
• Features
• Prerequisites
• Install
• Roadmap
• Getting help
• Contribute

It is a story as old as time. A stubborn, shell-dwelling, and melodramaticvimmer—envious of the features of modern text editors—spirals intodespair before he succumbs to thedark side. This is his config.

Doom is a configuration framework forGNU Emacs tailored for Emacs bankruptcyveterans who want less framework in their frameworks, a modicum of stability(and reproducibility) from their package manager, and the performance of a handrolled config (or better). It can be a foundation for your own config or aresource for Emacs enthusiasts to learn more about our favorite operatingsystem.

Its design is guided by these mantras:

• Gotta go fast. Startup and run-time performance are priorities. Doom goesbeyond by modifying packages to be snappier and load lazier.
• Close to metal. There's less between you and vanilla Emacs by design.That's less to grok and less to work around when you tinker. Internals oughtto be written as if reading them were part of Doom's UX, and it is!
• Opinionated, but not stubborn. Doom is about reasonable defaults andcurated opinions, but use as little or as much of it as you like.
• Your system, your rules. You know better. At least, Doom hopes so! Itwon'tautomatically install system dependencies (and will force plugins notto either). Rely ondoom doctor to tell you what's missing.
• Nix/Guix is a great idea! The Emacs ecosystem is temperamental. Thingsbreak and they break often. Disaster recovery should be a priority! Doom'spackage management should be declarative and your private config reproducible,and comes with a means to roll back releases and updates (still a WIP).

Check outthe FAQ for answers to common questions about the project.

• Minimalistic good looks inspired by modern editors.
• Curated and sane defaults for many packages, (major) OSes, and Emacs itself.
• A modular organizational structure for separating concerns in your config.
• A standard library designed to simplify your elisp bike shedding.
• A declarativepackage management system (powered bystraight.el) with a command line interface. Install packages from anywhere,not just (M)ELPA, and pin them to any commit.
• Optional vim emulation powered byevil-mode, including ports of popular vimplugins likevim-sneak,vim-easymotion,vim-unimpaired andmore!
• Opt-in LSP integration for many languages, usinglsp-mode oreglot
• Support formany programming languages. Includes syntax highlighting,linters/checker integration, inline code evaluation, code completion (wherepossible), REPLs, documentation lookups, snippets, and more!
• Support formany tools, like docker, pass, ansible, terraform, and more.
• A Spacemacs-esquekeybinding scheme, centered around leaderand localleader prefix keys (SPC andSPCm forevil users,C-c andC-c l for vanilla users).
• A rule-basedpopup manager to control how temporary buffersare displayed (and disposed of).
• Per-file indentation style detection andeditorconfig integration. Letsomeone else argue about tabs vsspaces.
• Project-management tools and framework-specific minor modes with their ownsnippets libraries.
• Project search (and replace) utilities, powered byripgrep andivy orhelm.
• Isolated and persistent workspaces (also substitutes for vim tabs).
• Support for Chinese and Japanese input systems.
• Save a snapshot of your shell environment to a file for Emacs to load atstartup. No more struggling to get Emacs to inherit yourPATH, among otherthings.

• Git 2.23+
• Emacs 27.1–30.1 (Recommended: 30.1 +native-comp)
• ripgrep 11.0+
• GNUfind
• OPTIONAL:fd 7.3.0+ (improves file indexing performance for some commands)

git clone --depth 1 https://github.com/doomemacs/doomemacs~/.config/emacs~/.config/emacs/bin/doom install

Thenread our Getting Started guide to be walked throughinstalling, configuring and maintaining Doom Emacs.

It's a good idea to add~/.config/emacs/bin to yourPATH! Otherbin/doomcommands you should know about:

• doom sync to synchronize your private config with Doom by installing missingpackages, removing orphaned packages, and regenerating caches. Run thiswhenever you modify your privateinit.el orpackages.el, or install/removean Emacs package through your OS package manager (e.g. mu4e or agda).
• doom upgrade to update Doom to the latest release & all installed packages.
• doom doctor to diagnose common issues with your system and config.
• doom env to dump a snapshot of your shell environment to a file that Doomwill load at startup. This allows Emacs to inherit yourPATH, among otherthings.

Doom is an active and ongoing project. To make that development moretransparent, its roadmap (and other concerns) are published across three githubproject boards and a newsletter:

• Development Roadmap
• Packages under review:lists plugins we are watching and considering for inclusion, and what theirstatus for inclusion is. Please consult this list before requesting newpackages/features.

• Upstream bugs: listsissues that originate from elsewhere, and whether or not we have localworkarounds or temporary fixes for them.
• Doom's newsletter (not finished) will contain changelogs in betweenreleases.

Emacs is no journey of a mere thousand miles. Youwill run into problems andmysterious errors. When you do, here are some places you can look for help:

• Our documentation covers many use cases.
  • The Configuration section covers how to configure Doom andits packages.
  • The Package Management section covers how to installand disable packages.
  • This section explains thebin/doom script's most importantcommands.
  • This section lists some common configuration mistakes newusers make, when migrating a config from another distro or their own.
  • This answer shows you how to add your own themes to yourprivate config.
  • This answer shows you how to change the default font.
  • Your issue may be documented in theFAQ.
• With Emacs built-in help system documentation is a keystroke away:
  • For functions:SPC h f orC-h f
  • For variables:SPC h v orC-h v
  • For a keybind:SPC h k orC-h k
  • To search available keybinds:SPC h b b orC-h b b
• Runbin/doom doctor to detect common issues with your developmentenvironment and private config.
• Check out theFAQ orCommunity FAQs, in case your questionhas already been answered.
• SearchDoom's issue trackerin case your issue was already reported.
• Hop onour Discord server; it's active and friendly! Keep an eye onthe #announcements channel, where I announce breaking updates and releases.

Doom is a labor of love and incurable madness, but I'm only one guy. Doomwouldn't be where it is today without your help. I welcome contributions of anykind!

• I ❤️ pull requests and bug reports (see theContributingGuidelines)!
• Don't hesitate totell me my Elisp-fusucks, but pleasetell me why.
• Hop onour Discord server and say hi! Help others, hang out or talkto me about Emacs, gamedev, programming, physics, pixel art, anime, gaming --anything you like. Nourish this lonely soul.
• If you'd like to support my work financially, buy me a drink throughliberapay orpaypal. My work contends with studies, adventures in indiegamedev and freelance work. Donations help me allocate more time to my Emacsand OSS capers.