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 "honeydew")

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. Alt+x describe-variable to see its value.

Start Emacs Without Loading Init File

You can start emacs without loading init file. This is useful if you made a syntax error 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; -*-
;; Emacs settings plain gnu emacs only
;; 2019-11-06
;; http://ergoemacs.org/emacs/emacs_init_index.html

;; HHH___________________________________________________________________
;; initial window and default window

(setq inhibit-startup-screen t)

(if (display-graphic-p)
    (setq initial-frame-alist
            (tool-bar-lines . 0)
            (background-color . "honeydew")
            (width . 106)
            (height . 56)
            ;; (left . 50)
            ;; (top . 50)
  (setq initial-frame-alist '( (tool-bar-lines . 0))))

(setq default-frame-alist
        (tool-bar-lines . 0)
        (background-color . "honeydew")
        (width . 100)
        (height . 55)))

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

;; HHH___________________________________________________________________
;; 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)
(global-auto-revert-mode 1)

;; HHH___________________________________________________________________
;; 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)

;; HHH___________________________________________________________________

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

;; HHH___________________________________________________________________

(setq set-mark-command-repeat-pop t)
(setq mark-ring-max 5)
(setq global-mark-ring-max 5)

;; HHH___________________________________________________________________
;; Emacs: Font Setup http://ergoemacs.org/emacs/emacs_list_and_set_font.html

;; set default font
  ((string-equal system-type "windows-nt")
   (if (member "Consolas" (font-family-list)) "Consolas" 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))
 t t)

;; set font for emoji
 '(#x1f300 . #x1fad0)
  ((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")
  ((member "Apple Color Emoji" (font-family-list)) "Apple Color Emoji"))
 ;; Apple Color Emoji should be before Symbola, but Richard Stallman skum disabled it.
 ;; GNU Emacs Removes Color Emoji Support on the Mac
 ;; http://ergoemacs.org/misc/emacs_macos_emoji.html

;; set font for chinese characters
 '(#x4e00 . #x9fff)
  ((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")))))

;; HHH___________________________________________________________________

  ;; minibuffer setup
  (setq enable-recursive-minibuffers t)
  (savehist-mode 1)
  ;; 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))))

  ;; minibuffer enhanced completion
  (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))

  ;; make buffer switch command do suggestions, also for find-file command
  (require 'ido)
  (ido-mode 1)

  ;; show choices vertically
  (if (version< emacs-version "25")
        (make-local-variable 'ido-separator)
        (setq ido-separator "\n"))
      (make-local-variable 'ido-decorations)
      (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)
  ;; stop ido from suggesting when naming new file
  (when (boundp 'ido-minor-mode-map-entry)
    (define-key (cdr ido-minor-mode-map-entry) [remap write-file] nil)))

;; HHH___________________________________________________________________

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

;; HHH___________________________________________________________________
;;; editing related

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

(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
Version 2019-02-22"
  (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://ergoemacs.org/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)

;; HHH___________________________________________________________________
;; 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 4)

(setq sentence-end-double-space nil )

;; HHH___________________________________________________________________

;; load emacs 24's package system. Add MELPA repository.
(when (>= emacs-major-version 24)
  (require 'package)
   ;; '("melpa" . "http://stable.melpa.org/packages/") ; many packages won't show if using stable
   '("melpa" . "https://melpa.org/packages/")

;; HHH___________________________________________________________________

 ;; Make whitespace-mode with very basic background coloring for whitespaces.
  ;; http://ergoemacs.org/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

;; HHH___________________________________________________________________
;; edit related

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

;; HHH___________________________________________________________________

;; convenient
(defalias 'yes-or-no-p 'y-or-n-p)
(defalias 'rs 'replace-string)
(defalias 'lcd 'list-colors-display)
(defalias 'ds 'desktop-save)

(defalias 'dsm 'desktop-save-mode)
(defalias 'elm 'emacs-lisp-mode)
(defalias 'hm 'html-mode)
(defalias 'jsm 'js-mode)
(defalias 'fm 'fundamental-mode)
(defalias 'ssm 'shell-script-mode)
(defalias 'om 'org-mode)

(defalias 'ms 'magit-status)
(defalias 'xnp 'xah-new-page)
(defalias 'xfc 'xah-find-count)
(defalias 'xcm 'xah-css-mode)
(defalias 'xem 'xah-elisp-mode)
(defalias 'xhm 'xah-html-mode)
(defalias 'xjm 'xah-js-mode)
(defalias 'xcm 'xah-clojure-mode)

;; no want tpu-edt
(defalias 'tpu-edt 'forward-char)
(defalias 'tpu-edt-on 'forward-char)

;; HHH___________________________________________________________________
  ;; org-mode
  ;; make “org-mode” syntax color code sections
  (setq org-src-fontify-natively t)
  (setq org-startup-folded nil)
  (setq org-return-follows-link t)
  (setq org-startup-truncated nil))

;; HHH___________________________________________________________________

(when (fboundp 'eww)
  (defun xah-rename-eww-buffer ()
    "Rename `eww-mode' buffer so sites open in new page.
URL `http://ergoemacs.org/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))

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

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

If you have a question, put $5 at patreon and message me on xah discord.
Or support me by Buy Xah Emacs Tutorial

Emacs Tutorial

Emacs Init

Emacs Keys


ELisp Examples

ELisp Write Major Mode

Emacs Init

Init Basics


text editing