Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit

* doom-modeline-core.el (doom-modeline-buffer-file-name-style):
Delete duplicate entry for `truncate-upto-project'.

Git stats


Failed to load latest commit information.


Build Status Release Tag License MELPA MELPA Stable

Table of Contents

A fancy and fast mode-line inspired by minimalism design.

It's integrated into Centaur Emacs, Doom Emacs and Spacemacs.


The doom-modeline was designed for minimalism, and offers:

  • A match count panel (for anzu, iedit, multiple-cursors, symbol-overlay, and evil-search, etc.)
  • An indicator for recording a macro
  • Current environment version (e.g. python, ruby, go, etc.) in the major-mode
  • A customizable mode-line height (see doom-modeline-height)
  • A minor modes segment which is compatible with minions
  • An error/warning count segment for flymake/flycheck
  • A workspace number/name segment for eyebrowse or tab-bar-mode
  • A perspective name segment for persp-mode
  • A window number segment for ace-window, winum and window-numbering
  • An indicator for modal editing state, including evil, overwrite, god, ryo and xah-fly-keys, etc.
  • An indicator for battery status
  • An indicator for current input method
  • An indicator for debug state
  • An indicator for remote host
  • An indicator for LSP state with lsp-mode or eglot
  • An indicator for GitHub notifications
  • An indicator for unread emails with mu4e-alert and gnus
  • An indicator for IRC notifications with circe, rcirc or erc
  • An indicator for buffer position which is compatible with nyan-mode or poke-line
  • An indicator for party parrot
  • An indicator for PDF page number with pdf-tools
  • An indicator for markdown/org preview with grip
  • Truncated file name, file icon, buffer state and project name in buffer information segment, which is compatible with project, projectile and find-file-in-project.
  • New mode-line for Info-mode buffers
  • New package mode-line for paradox
  • New mode-line for helm buffers
  • New mode-line for git-timemachine buffers



























From melpa, M-x package-install RET doom-modeline RET.

In init.el,

(require 'doom-modeline)
(doom-modeline-mode 1)


(add-hook 'after-init-hook #'doom-modeline-mode)


(use-package doom-modeline
  :ensure t
  :init (doom-modeline-mode 1))


(use-package doom-modeline
  :ensure t
  :hook (after-init . doom-modeline-mode))

This package is able to display icons if nerd-icons package and required fonts are installed. Run M-x nerd-icons-install-fonts to install the necessary fonts. Please refer to the installation guide.

Strongly recommend to use doom-themes at the same time.


Run M-x customize-group RET doom-modeline RET or set the variables.

;; If non-nil, cause imenu to see `doom-modeline' declarations.
;; This is done by adjusting `lisp-imenu-generic-expression' to
;; include support for finding `doom-modeline-def-*' forms.
;; Must be set before loading doom-modeline.
(setq doom-modeline-support-imenu t)

;; How tall the mode-line should be. It's only respected in GUI.
;; If the actual char height is larger, it respects the actual height.
(setq doom-modeline-height 25)

;; How wide the mode-line bar should be. It's only respected in GUI.
(setq doom-modeline-bar-width 4)

;; Whether to use hud instead of default bar. It's only respected in GUI.
(setq doom-modeline-hud nil)

;; The limit of the window width.
;; If `window-width' is smaller than the limit, some information won't be
;; displayed. It can be an integer or a float number. `nil' means no limit."
(setq doom-modeline-window-width-limit 85)

;; How to detect the project root.
;; nil means to use `default-directory'.
;; The project management packages have some issues on detecting project root.
;; e.g. `projectile' doesn't handle symlink folders well, while `project' is unable
;; to hanle sub-projects.
;; You can specify one if you encounter the issue.
(setq doom-modeline-project-detection 'auto)

;; Determines the style used by `doom-modeline-buffer-file-name'.
;; Given ~/Projects/FOSS/emacs/lisp/comint.el
;;   auto => emacs/l/comint.el (in a project) or comint.el
;;   truncate-upto-project => ~/P/F/emacs/lisp/comint.el
;;   truncate-from-project => ~/Projects/FOSS/emacs/l/comint.el
;;   truncate-with-project => emacs/l/comint.el
;;   truncate-except-project => ~/P/F/emacs/l/comint.el
;;   truncate-upto-root => ~/P/F/e/lisp/comint.el
;;   truncate-all => ~/P/F/e/l/comint.el
;;   truncate-nil => ~/Projects/FOSS/emacs/lisp/comint.el
;;   relative-from-project => emacs/lisp/comint.el
;;   relative-to-project => lisp/comint.el
;;   file-name => comint.el
;;   buffer-name => comint.el<2> (uniquify buffer name)
;; If you are experiencing the laggy issue, especially while editing remote files
;; with tramp, please try `file-name' style.
;; Please refer to
(setq doom-modeline-buffer-file-name-style 'auto)

;; Whether display icons in the mode-line.
;; While using the server mode in GUI, should set the value explicitly.
(setq doom-modeline-icon t)

;; Whether display the icon for `major-mode'. It respects `doom-modeline-icon'.
(setq doom-modeline-major-mode-icon t)

;; Whether display the colorful icon for `major-mode'.
;; It respects `nerd-icons-color-icons'.
(setq doom-modeline-major-mode-color-icon t)

;; Whether display the icon for the buffer state. It respects `doom-modeline-icon'.
(setq doom-modeline-buffer-state-icon t)

;; Whether display the modification icon for the buffer.
;; It respects `doom-modeline-icon' and `doom-modeline-buffer-state-icon'.
(setq doom-modeline-buffer-modification-icon t)

;; Whether display the time icon. It respects variable `doom-modeline-icon'.
(setq doom-modeline-time-icon t)

;; Whether to use unicode as a fallback (instead of ASCII) when not using icons.
(setq doom-modeline-unicode-fallback nil)

;; Whether display the buffer name.
(setq doom-modeline-buffer-name t)

;; Whether highlight the modified buffer name.
(setq doom-modeline-highlight-modified-buffer-name t)

;; Whether display the minor modes in the mode-line.
(setq doom-modeline-minor-modes nil)

;; If non-nil, a word count will be added to the selection-info modeline segment.
(setq doom-modeline-enable-word-count nil)

;; Major modes in which to display word count continuously.
;; Also applies to any derived modes. Respects `doom-modeline-enable-word-count'.
;; If it brings the sluggish issue, disable `doom-modeline-enable-word-count' or
;; remove the modes from `doom-modeline-continuous-word-count-modes'.
(setq doom-modeline-continuous-word-count-modes '(markdown-mode gfm-mode org-mode))

;; Whether display the buffer encoding.
(setq doom-modeline-buffer-encoding t)

;; Whether display the indentation information.
(setq doom-modeline-indent-info nil)

;; Whether display the total line number。
(setq doom-modeline-total-line-number nil)

;; If non-nil, only display one number for checker information if applicable.
(setq doom-modeline-checker-simple-format t)

;; The maximum number displayed for notifications.
(setq doom-modeline-number-limit 99)

;; The maximum displayed length of the branch name of version control.
(setq doom-modeline-vcs-max-length 12)

;; Whether display the workspace name. Non-nil to display in the mode-line.
(setq doom-modeline-workspace-name t)

;; Whether display the perspective name. Non-nil to display in the mode-line.
(setq doom-modeline-persp-name t)

;; If non nil the default perspective name is displayed in the mode-line.
(setq doom-modeline-display-default-persp-name nil)

;; If non nil the perspective name is displayed alongside a folder icon.
(setq doom-modeline-persp-icon t)

;; Whether display the `lsp' state. Non-nil to display in the mode-line.
(setq doom-modeline-lsp t)

;; Whether display the GitHub notifications. It requires `ghub' package.
(setq doom-modeline-github nil)

;; The interval of checking GitHub.
(setq doom-modeline-github-interval (* 30 60))

;; Whether display the modal state.
;; Including `evil', `overwrite', `god', `ryo' and `xah-fly-keys', etc.
(setq doom-modeline-modal t)

;; Whether display the modal state icon.
;; Including `evil', `overwrite', `god', `ryo' and `xah-fly-keys', etc.
(setq doom-modeline-modal-icon t)

;; Whether display the modern icons for modals.
(setq doom-modeline-modal-modern-icon t)

;; When non-nil, always show the register name when recording an evil macro.
(setq doom-modeline-always-show-macro-register nil)

;; Whether display the mu4e notifications. It requires `mu4e-alert' package.
(setq doom-modeline-mu4e nil)
;; also enable the start of mu4e-alert

;; Whether display the gnus notifications.
(setq doom-modeline-gnus t)

;; Whether gnus should automatically be updated and how often (set to 0 or smaller than 0 to disable)
(setq doom-modeline-gnus-timer 2)

;; Wheter groups should be excludede when gnus automatically being updated.
(setq doom-modeline-gnus-excluded-groups '(""))

;; Whether display the IRC notifications. It requires `circe' or `erc' package.
(setq doom-modeline-irc t)

;; Function to stylize the irc buffer names.
(setq doom-modeline-irc-stylize 'identity)

;; Whether display the battery status. It respects `display-battery-mode'.
(setq doom-modeline-battery t)

;; Whether display the time. It respects `display-time-mode'.
(setq doom-modeline-time t)

;; Whether display the misc segment on all mode lines.
;; If nil, display only if the mode line is active.
(setq doom-modeline-display-misc-in-all-mode-lines t)

;; Whether display the environment version.
(setq doom-modeline-env-version t)
;; Or for individual languages
(setq doom-modeline-env-enable-python t)
(setq doom-modeline-env-enable-ruby t)
(setq doom-modeline-env-enable-perl t)
(setq doom-modeline-env-enable-go t)
(setq doom-modeline-env-enable-elixir t)
(setq doom-modeline-env-enable-rust t)

;; Change the executables to use for the language version string
(setq doom-modeline-env-python-executable "python") ; or `python-shell-interpreter'
(setq doom-modeline-env-ruby-executable "ruby")
(setq doom-modeline-env-perl-executable "perl")
(setq doom-modeline-env-go-executable "go")
(setq doom-modeline-env-elixir-executable "iex")
(setq doom-modeline-env-rust-executable "rustc")

;; What to display as the version while a new one is being loaded
(setq doom-modeline-env-load-string "...")

;; By default, almost all segments are displayed only in the active window. To
;; display such segments in all windows, specify e.g.
(setq doom-modeline-always-visible-segments '(mu4e irc))

;; Hooks that run before/after the modeline version string is updated
(setq doom-modeline-before-update-env-hook nil)
(setq doom-modeline-after-update-env-hook nil)


  1. How to display icons correctly?

    nerd-icons are necessary. Then run M-x nerd-icons-install-fonts to install the resource fonts. On Windows, the fonts should be installed manually. nerd-icons supports both GUI and TUI.

    If you don't like color icons, (setq nerd-icons-color-icons nil) to disable it. Please refer to nerd-icons.el for details.

    If you prefer all-the-icons, please use release 3.4.0. It hasn't been supported since 4.0.0.

  2. I am experiencing the laggy issue, how to resolve it?

    Add this configuration into your init file:

    ;; Don’t compact font caches during GC.
    (setq inhibit-compacting-font-caches t)
  3. A ridiculous path is displayed on the mode-line while visiting a symbolink.

    It's the default behaviors of Vanilla Emacs. If you want to display the real names, please put this into your init file.

    (setq find-file-visit-truename t)

    If the file is controlled by vc, refer to the documentation of vc-follow-symlinks.

  4. Why doesn't change of branch reflect in modeline?

    Actually it's related to magit and vc-mode.

  5. Can I add my mode-line segments myself? How to do that? How can I define my own mode-line?

    There are two methods.

    • If the information is simple, just add to mode-line-misc-info or global-mode-string.

    • Use doom-modeline-def-modeline to define your own mode-line and set it as default.

      For example:

      ;; Define your custom doom-modeline
      (doom-modeline-def-modeline 'my-simple-line
        '(bar matches buffer-info remote-host buffer-position parrot selection-info)
        '(misc-info minor-modes input-method buffer-encoding major-mode process vcs checker))
      ;; Set default mode-line
      (add-hook 'doom-modeline-mode-hook
                (lambda ()
                  (doom-modeline-set-modeline 'my-simple-line 'default)))
      ;; Configure other mode-lines based on major modes
      (add-to-list 'doom-modeline-mode-alist '(my-mode . my-simple-line))
      ;; Or disable other mode-lines
      (setq 'doom-modeline-mode-alist nil)
  6. How to specify font family and size in modeline?

    For example:

    (setq doom-modeline-height 1) ; optional
    (if (facep 'mode-line-active)
        (set-face-attribute 'mode-line-active nil :family "Noto Sans" :height 100) ; For 29+
      (set-face-attribute 'mode-line nil :family "Noto Sans" :height 100))
    (set-face-attribute 'mode-line-inactive nil :family "Noto Sans" :height 100)


    (setq doom-modeline-height 1) ; optional
      '(mode-line ((t (:family "Noto Sans" :height 0.9))))
      '(mode-line-active ((t (:family "Noto Sans" :height 0.9)))) ; For 29+
      '(mode-line-inactive ((t (:family "Noto Sans" :height 0.9)))))

    Please refer to #189 and #301.

  7. The right side of the modeline is cut off. How to fix it?

    • Tweak nerd-icons-scale-factor. e.g. (setq nerd-icons-scale-factor 1.1)
    • Use another font family or size. See above.
  8. How to disable symbolic links expanding in mode-line?

    If you encounter the issue like this


    please try this:

    ;; built-in `project' on 26+
    (setq doom-modeline-project-detection 'project)
    ;; or `find-in-project' if it's installed
    (setq doom-modeline-project-detection 'ffip)

    For more details, refer to #209 and #224.

  9. Can doom-modeline show match count while search with evil-search?

    Yes. For better experience, should enable anzu-mode and load evil-anzu.

  10. How to show that the R is running in inferior ess R mode?

    The ess R mode modifies mode-line-buffer-identification directly to display the status. To display the status in doom-modeline, you can add the status to mode-line-process or global-mode-string as below.

    (add-hook 'inferior-ess-mode-hook
          (lambda ()
            (add-to-list 'mode-line-process '(:eval (nth ess--busy-count ess-busy-strings)))))
  11. How to display company mode-line information?

    Enable doom-modeline-minor-modes or (add-to-list 'global-mode-string company-lighter).

  12. How to display LaTeX compilation information in the mode line?

    Use process package. Refer to #387 for more details.

    (require 'procress)
    (add-hook 'LaTeX-mode-hook #'procress-auctex-mode)


If you think it's helpful for you, please consider paying a cup of coffee for me. Thank you! 😄

Alipay      Wechat Pay

PayPal      Buy Me A Coffee