Emacs Beginner's HOWTO: start editing with GNU Emacs 31

Updated November 2026

GNU Emacs is a text editor you can grow into. On day one you need about fifteen keys. After that, its built-in help, package manager, Org mode and language server client turn it into a full workbench. This page gets you from first start to a small, useful configuration.

The classic Emacs Beginner's HOWTO from 2001 is kept by the LDP at tldp.org. Much of its advice (VM, BBDB, the old .emacs file) has been replaced by tools that now ship inside Emacs.

Everything below works in Emacs 30 and 31. Where a feature is newer, the page says so. Ubuntu 24.04 LTS ships Emacs 29.3, which lacks the built-in which-key; the rest of the page works there too.

Install and start Emacs

sudo apt install emacs          # Debian, Ubuntu (GTK build); emacs-nox = terminal only
sudo dnf install emacs          # Fedora (31.1 in Fedora 45, 30.2 in Fedora 44)
sudo pacman -S emacs            # Arch (31.1 as of November 2026)

On Debian there is also emacs-pgtk, a build made for Wayland desktops. Debian notes that it still works less well than the standard GTK build in some respects, so pick it only if you run Wayland. Start Emacs from the menu, or type emacs file.txt. Use emacs -nw to run it inside the terminal.

Read the key notation

Emacs documentation writes keys like this:

The most important key is C-g. It cancels whatever half-typed command you are in. When confused, press it two or three times.

The keys for day one

Basic Emacs keys
KeyDoes
C-x C-fopen (find) a file; type a new name to create one
C-x C-ssave
C-x C-wsave as
C-x C-cquit (asks about unsaved files)
C-/undo
C-s / C-rsearch forward / backward as you type
M-%search and replace, asking at each match
C-SPCstart selecting (set the mark), then move
C-w / M-w / C-ycut / copy / paste ("kill", "copy", "yank")
C-x bswitch to another open file (buffer)
C-x kclose a buffer
C-x 2 / C-x 3 / C-x o / C-x 1split below / split right / go to other window / keep only this one
M-xrun any command by name, with completion

Arrow keys, Home, End and Page Up/Down work as usual. If you would rather use Ctrl+C, Ctrl+X and Ctrl+V for copy, cut and paste, turn on cua-mode (in the Options menu, or in your init file, shown below).

The best half hour you can spend: press C-h t for the built-in tutorial.

Ask Emacs itself

Emacs describes itself. Every key, command and setting has documentation one key away:

Since Emacs 30, which-key is built in. Turn it on with M-x which-key-mode. Then type C-x and wait a second, and a panel lists every key that can follow.

Modes: major and minor

Each buffer has one major mode that knows its file type: python-mode, c-mode, org-mode, text-mode. It decides indentation, colors and special keys. Emacs picks it from the file name. Minor modes are extra features you switch on and off, such as display-line-numbers-mode, auto-fill-mode (wrap lines as you type) or flyspell-mode (spell checking). Each mode name is also a command, so M-x display-line-numbers-mode toggles it.

Your init file

Emacs reads your settings at start-up from an init file. It looks for ~/.emacs.el, ~/.emacs and ~/.emacs.d/init.el, in that order. It uses the XDG location ~/.config/emacs/init.el only if ~/.emacs.el, ~/.emacs and the ~/.emacs.d directory do not exist. If neither ~/.config/emacs nor ~/.emacs.d exists, Emacs creates ~/.emacs.d on its first start. For a fresh start, run mkdir -p ~/.config/emacs before you start Emacs for the first time, and make sure the older names do not exist. Here is a small one to begin with:

;;; ~/.config/emacs/init.el
(setopt inhibit-startup-screen t)        ; open straight to *scratch*
(setopt make-backup-files nil)           ; no file~ copies next to your files
(global-display-line-numbers-mode 1)     ; line numbers everywhere
(column-number-mode 1)                   ; column in the mode line
(which-key-mode 1)                       ; key hints (Emacs 30+)
(load-theme 'modus-operandi t)           ; built-in, high-contrast light theme
;; (cua-mode 1)                          ; uncomment for C-c/C-x/C-v

;; Keep settings made through M-x customize in their own file
(setopt custom-file (locate-user-emacs-file "custom.el"))
(load custom-file 'noerror)

setopt (Emacs 29 and later) sets a user option the way the Customize interface does. Use setq for plain variables. After editing, restart Emacs, or run M-x eval-buffer in the init file. Prefer menus? M-x customize lets you browse and save every option.

Install packages

Emacs has a package manager. Out of the box it uses two archives run for Emacs users: GNU ELPA and NonGNU ELPA. M-x list-packages shows what is available. Press i to mark a package, then x to install it.

For a configuration you can copy to another machine, use use-package, which ships with Emacs 29 and later. With :ensure t, it installs the package if it is missing:

;; Magit: a Git interface (NonGNU ELPA)
(use-package magit
  :ensure t
  :bind ("C-x g" . magit-status))

;; Vertico: vertical completion in the minibuffer (GNU ELPA)
(use-package vertico
  :ensure t
  :init (vertico-mode 1))

Many more packages live in MELPA, a large community archive. Add it to package-archives only if you need something that is not in the two default archives. Install only what you understand. Every package adds code that runs with your permissions.

Org mode in five minutes

Org mode (bundled, version 9.8 in Emacs 31) is a plain-text format for notes, to-do lists and documents. Open a file ending in .org and type:

* Projects
** TODO Write release notes
   DEADLINE: <2026-11-20 Fri>
** DONE Migrate CVS to Git
* Notes
- Org text is just text; any editor can read it.

Code intelligence with Eglot

Eglot, built in since Emacs 29, connects Emacs to language servers through the Language Server Protocol (LSP). That gives you completion, go-to-definition, error checking and renaming for most languages. Install a server first:

sudo apt install python3-pylsp clangd       # Debian/Ubuntu: Python and C/C++
sudo dnf install python3-lsp-server clang-tools-extra   # Fedora

Open a source file and run M-x eglot. Eglot knows the usual servers for each language (pylsp for Python, clangd for C, rust-analyzer for Rust, and many more). To start it automatically:

(add-hook 'python-mode-hook #'eglot-ensure)
(add-hook 'c-mode-hook #'eglot-ensure)

Then M-. jumps to a definition, M-, jumps back, and M-x eglot-rename renames a symbol across the project. Errors are underlined through Flymake. M-x flymake-show-buffer-diagnostics lists them.

Emacs also has tree-sitter modes (for example python-ts-mode) with faster, more accurate highlighting. They need a grammar library for each language. Emacs 31 adds the options treesit-enabled-modes, to switch these modes on, and treesit-auto-install-grammar, to fetch missing grammars. Beginners can safely skip tree-sitter at first.

Mistakes beginners make

Next: track your work with Git (Magit makes it pleasant), or write documentation with DocBook, AsciiDoc or Markdown.

Sources