Emacs: Init File Tutorial

By Xah Lee. Date: . Last updated: .

This page shows you how to set up many preferences in emacs.

The following assume you are using GNU Emacs version 25.1 (released in 2016) or later.

What is Init File

Emacs init file is a file emacs loads when it starts up. It is used to customize emacs.

Emacs init file is also known as “dot emacs file”.

Where is Init File

By default, there is no init file. You have to create the file yourself, and add emacs lisp code to it.

Create a file with this content:

(set-background-color "ivory")

Save it at ~/.emacs.d/init.el

On linux and Mac, by default, emacs look for init file at the following filepath, in order:

On Microsoft Windows:

[see Emacs in Microsoft Windows FAQ]

It's ok to delete your init file and start over.

Variable. This variable stores the init file path once emacs found one. [see Emacs: Show Variable Value]

Start Emacs Without Loading Init File

You can start emacs without loading init file. This is useful if you made a mistake in your init file.

# start emacs without loading init file
emacs -q
-q or --no-init-file
Don't load your personal init file.
-Q or --quick
same as --no-init-file --no-site-file --no-splash.

On Windows, to start emacs with command line options, you can use PowerShell. [see PowerShell Tutorial]

 PowerShell start emacs 2021-06-29
PowerShell start emacs 2021-06-29

Or, create a alias of the emacs icon, and in properties, set the launch options. [see Emacs in Microsoft Windows FAQ]

Modify Init File Without Restarting Emacs

For simple changes, you do not need to restart emacs.

After you added some new code to init file, just select the region, then Alt+x eval-region. [see Evaluate Emacs Lisp Code]

Then, the code/preference you added will become effective immediately.

Reload Init File

Note, some packages, or elisp code, may behave differently when loaded twice. And some code may not work by simply running it by itself (it may assume some other code has been loaded before or after.).

If you have a problem, restart emacs.

Sample Init File

Here's a sample init file, that sets all basics. No external packages are required.

;; -*- coding: utf-8; lexical-binding: t; -*-
;; basic gnu emacs settings. Everything in this file is for plain gnu emacs only.
;; for emacs 28 or later.
;; 2022-06-20

;; UTF-8 as default encoding
(set-language-environment "UTF-8")
(set-default-coding-systems 'utf-8-unix)

;; initial window and default window

(setq inhibit-startup-screen t)

(setq default-frame-alist
      (if (display-graphic-p)
          '((tool-bar-lines . 0)
            (background-color . "honeydew")
            (width . 80)
            (height . 46))
        '((tool-bar-lines . 0))))

;; Emacs: Font Setup http://xahlee.info/emacs/emacs/emacs_list_and_set_font.html

  ((string-equal system-type "windows-nt")
   (if (member "Consolas" (font-family-list)) "Consolas-14" nil ))
  ((string-equal system-type "darwin")
   (if (member "Menlo" (font-family-list)) "Menlo-16" nil ))
  ((string-equal system-type "gnu/linux")
   (if (member "DejaVu Sans Mono" (font-family-list)) "DejaVu Sans Mono" nil ))
  (t nil))
 nil t

;; set font for symbols (symbol . [8220 8704 9472])
  ((string-equal system-type "windows-nt")
    ((member "Segoe UI Symbol" (font-family-list)) "Segoe UI Symbol")))
  ((string-equal system-type "darwin")
    ((member "Apple Symbols" (font-family-list)) "Apple Symbols")))
  ((string-equal system-type "gnu/linux")
    ((member "Symbola" (font-family-list)) "Symbola")))))

  ;; set font for emoji (if before emacs 28, should come after setting symbols. emacs 28 now has 'emoji . before, emoji is part of 'symbol)
   (if (version< emacs-version "28.1")
       '(#x1f300 . #x1fad0)
    ((member "Apple Color Emoji" (font-family-list)) "Apple Color Emoji")
    ((member "Noto Color Emoji" (font-family-list)) "Noto Color Emoji")
    ((member "Noto Emoji" (font-family-list)) "Noto Emoji")
    ((member "Segoe UI Emoji" (font-family-list)) "Segoe UI Emoji")
    ((member "Symbola" (font-family-list)) "Symbola"))))

;; set font for cuneiform
  ((string-equal system-type "windows-nt")
    ((member "Segoe UI Historic" (font-family-list)) "Segoe UI Historic")))
  ((string-equal system-type "darwin")
    ((member "Noto Sans Cuneiform Regular" (font-family-list)) "Noto Sans Cuneiform Regular")))
  ((string-equal system-type "gnu/linux")
    ((member "Noto Sans Cuneiform Regular" (font-family-list)) "Noto Sans Cuneiform Regular")))))

  ((string-equal system-type "windows-nt")
    ((member "Segoe UI Historic" (font-family-list)) "Segoe UI Historic")))
  ((string-equal system-type "darwin")
    ((member "Noto Sans Phoenician Regular" (font-family-list)) "Noto Sans Phoenician Regular")))
  ((string-equal system-type "gnu/linux")
    ((member "Noto Sans Phoenician Regular" (font-family-list)) "Noto Sans Phoenician Regular")))))

  ((string-equal system-type "windows-nt")
    ((member "Segoe UI Symbol" (font-family-list)) "Segoe UI Symbol")))
  ((string-equal system-type "darwin")
    ((member "Apple Symbols" (font-family-list)) "Apple Symbols")))
  ((string-equal system-type "gnu/linux")
    ((member "Noto Sans Deseret" (font-family-list)) "Noto Sans Deseret")))))

  ((string-equal system-type "windows-nt")
    ((member "Segoe UI Historic" (font-family-list)) "Segoe UI Historic")))
  ((string-equal system-type "darwin")
    ((member "Apple Symbols" (font-family-list)) "Apple Symbols")))
  ((string-equal system-type "gnu/linux")
    ((member "Noto Sans Shavian Regular" (font-family-list)) "Noto Sans Shavian Regular")))))

  ((string-equal system-type "windows-nt")
    ((member "Segoe UI Historic" (font-family-list)) "Segoe UI Historic")))
  ((string-equal system-type "darwin")
    ((member "Noto Sans Egyptian Hieroglyphs" (font-family-list)) "Noto Sans Egyptian Hieroglyphs")))
  ((string-equal system-type "gnu/linux")
    ((member "Aegyptus" (font-family-list)) "Aegyptus")))))

;; set font for chinese
  ((string-equal system-type "windows-nt")
    ((member "Microsoft YaHei" (font-family-list)) "Microsoft YaHei")
    ((member "Microsoft JhengHei" (font-family-list)) "Microsoft JhengHei")
    ((member "SimHei" (font-family-list)) "SimHei")))
  ((string-equal system-type "darwin")
    ((member "Hei" (font-family-list)) "Hei")
    ((member "Heiti SC" (font-family-list)) "Heiti SC")
    ((member "Heiti TC" (font-family-list)) "Heiti TC")))
  ((string-equal system-type "gnu/linux")
    ((member "WenQuanYi Micro Hei" (font-family-list)) "WenQuanYi Micro Hei")))))

;; backup and file related

(defun xah-save-all-unsaved ()
  "Save all unsaved files. no ask.
Version 2019-11-05"
  (save-some-buffers t ))

(if (version< emacs-version "27")
    (add-hook 'focus-out-hook 'xah-save-all-unsaved)
  (setq after-focus-change-function 'xah-save-all-unsaved))

(setq make-backup-files nil)
(setq backup-by-copying t)
(setq create-lockfiles nil)
(setq auto-save-default nil)

(require 'recentf)
(recentf-mode 1)

  ;; (desktop-save-mode 1)
  (setq desktop-restore-frames t)
  (setq desktop-auto-save-timeout 300)
  (setq desktop-globals-to-save nil)
  ;; (setq desktop-globals-to-save '(desktop-missing-file-warning tags-file-name tags-table-list search-ring regexp-search-ring register-alist file-name-history))
  (setq desktop-save t))

(global-auto-revert-mode 1)

;; user interface

(when (version<= "26.0.50" emacs-version )

(column-number-mode 1)
(blink-cursor-mode 0)
(setq use-dialog-box nil)

  ;; no need to warn
  (put 'narrow-to-region 'disabled nil)
  (put 'narrow-to-page 'disabled nil)
  (put 'upcase-region 'disabled nil)
  (put 'downcase-region 'disabled nil)
  (put 'erase-buffer 'disabled nil)
  (put 'scroll-left 'disabled nil)
  (put 'dired-find-alternate-file 'disabled nil)


  (require 'dired-x)
  (setq dired-dwim-target t)
  ;; (cond
  ;;  ((string-equal system-type "gnu/linux") (setq dired-listing-switches "-al --time-style long-iso"))
  ;;  ((string-equal system-type "darwin") (setq dired-listing-switches "-alh")))
  (setq dired-recursive-copies 'top)
  (setq dired-recursive-deletes 'top))


(setq set-mark-command-repeat-pop nil)
(setq mark-ring-max 10)
(setq global-mark-ring-max 10)


  ;; minibuffer setup
  (setq enable-recursive-minibuffers t)
  (savehist-mode 0)
  ;; big minibuffer height, for ido to show choices vertically
  (setq max-mini-window-height 0.5)
  ;; minibuffer, stop cursor going into prompt
   (quote (read-only t cursor-intangible t face minibuffer-prompt))))

(if (version< emacs-version "28.1")
        ;; make buffer switch command do suggestions, also for find-file command
        (require 'ido)
        (ido-mode 1)
        ;; show choices vertically
        (setf (nth 2 ido-decorations) "\n")
        ;; show any name that has the chars you typed
        (setq ido-enable-flex-matching t)
        ;; use current pane for newly opened file
        (setq ido-default-file-method 'selected-window)
        ;; use current pane for newly switched buffer
        (setq ido-default-buffer-method 'selected-window)
        ;; minibuffer enhanced completion icomplete
        (require 'icomplete)
        (icomplete-mode 1)
        ;; show choices vertically
        (setq icomplete-separator "\n")
        (setq icomplete-hide-common-prefix nil)
        (setq icomplete-in-buffer t)
        (define-key icomplete-minibuffer-map (kbd "<right>") 'icomplete-forward-completions)
        (define-key icomplete-minibuffer-map (kbd "<left>") 'icomplete-backward-completions)))
  (fido-vertical-mode 1))


;; remember cursor position
(if (version< emacs-version "25.0")
      (require 'saveplace)
      (setq-default save-place t))
  (save-place-mode 1))

;;; editing related

;; make typing delete/overwrites selected text
(delete-selection-mode 1)

;; disable shift select
(setq shift-select-mode nil)

(electric-pair-mode 1)

;; set highlighting brackets
(show-paren-mode 1)
(setq show-paren-style 'parenthesis)

;; for isearch-forward, make these equivalent: space newline tab hyphen underscore
(setq search-whitespace-regexp "[-_ \t\n]+")

(defun xah-toggle-search-whitespace ()
  "Set `search-whitespace-regexp' to nil or includes hyphen lowline tab newline.
Explanation: When in isearch (M-x `isearch-forward'), space key can also stand for other chars such as hyphen lowline tab newline. It depend on a regex. It's convenient. But sometimes you want literal. This command makes it easy to toggle.

Emacs Isearch Space Toggle
URL `http://xahlee.info/emacs/emacs/emacs_isearch_space.html'
Version 2019-02-22 2021-11-13"
  (if (string-equal search-whitespace-regexp nil)
        (setq search-whitespace-regexp "[-_ \t\n]+")
        (message "Space set to hyphen lowline tab newline space"))
      (setq search-whitespace-regexp nil)
      (message "Space set to literal."))))

;; 2015-07-04 bug of pasting in emacs.
;; http://debbugs.gnu.org/cgi/bugreport.cgi?bug=16737#17
;; http://xahlee.info/emacs/misc/emacs_bug_cant_paste_2015.html
;; (setq x-selection-timeout 300)
(setq save-interprogram-paste-before-kill t)
(setq x-select-enable-clipboard-manager nil)

;; indentation, end of line

(electric-indent-mode 0)

(set-default 'tab-always-indent 'complete)

;; no mixed tab space
(setq-default indent-tabs-mode nil)
 ; gnu emacs 23.1, 24.4.1 default is t

;; 4 is more popular than 8.
(setq-default tab-width 1)

(setq sentence-end-double-space nil )


;; load emacs 24's package system. Add MELPA repository.
(when (>= emacs-major-version 24)
  (require 'package)
   '("melpa" . "https://melpa.org/packages/")


  ;; Make whitespace-mode with very basic background coloring for whitespaces.
  ;; http://xahlee.info/emacs/emacs/whitespace-mode.html
  (setq whitespace-style (quote (face spaces tabs newline space-mark tab-mark newline-mark)))

  ;; Make whitespace-mode and whitespace-newline-mode use “¶” for end of line char and “▷” for tab.
  (setq whitespace-display-mappings
        ;; all numbers are unicode codepoint in decimal. e.g. (insert-char 182 1)
        '((space-mark 32 [183] [46]) ; SPACE 32 「 」, 183 MIDDLE DOT 「·」, 46 FULL STOP 「.」
          (newline-mark 10 [182 10]) ; LINE FEED,
          (tab-mark 9 [9655 9] [92 9]) ; tab

;; edit related

(setq hippie-expand-try-functions-list
        ;; try-expand-dabbrev-from-kill
        ;; try-expand-all-abbrevs
        ;; try-expand-list
        ;; try-expand-line


(if (version< emacs-version "28.1")
    (defalias 'yes-or-no-p 'y-or-n-p)
  (setq use-short-answers t))


(when (fboundp 'eww)
  (defun xah-rename-eww-buffer ()
    "Rename `eww-mode' buffer so sites open in new page.
URL `http://xahlee.info/emacs/emacs/emacs_eww_web_browser.html'
Version 2017-11-10"
    (let (($title (plist-get eww-data :title)))
      (when (eq major-mode 'eww-mode )
        (if $title
            (rename-buffer (concat "eww " $title ) t)
          (rename-buffer "eww" t)))))

  (add-hook 'eww-after-render-hook 'xah-rename-eww-buffer))

;; 2021-12-21. fuck Alan Mackenzie
;; Emacs Lisp Doc String Curly Quote Controversy
;; http://xahlee.info/emacs/misc/emacs_lisp_curly_quote_controversy.html
(setq text-quoting-style 'straight)

(setq mouse-highlight nil)

(setq line-move-visual t)

(setq byte-compile-docstring-max-column 999)

(if (version< emacs-version "28.1")
  (setq mode-line-compact t))


;; (global-tab-line-mode)

(tooltip-mode -1)

much thanks to jcs. http://irreal.org/blog/

Thanks to Ivan Kozik (http://ludios.org/ivank/) for a tip.

ErgoEmacs mascot-s276x226
Buy Xah Emacs Tutorial

Emacs Init

Init Basics



Text Editing



Restore Things





Advanced Init Tips