---

Quick Start

If you don't have an existing Emacs setup and want to run Spacemacs as your configuration, and if you have all prerequisites installed, you can install Spacemacs with one line:

• shell:

  git clone https://github.com/syl20bnr/spacemacs $HOME/.emacs.d
  

• Windows PowerShell:

  git clone https://github.com/syl20bnr/spacemacs $HOME/.emacs.d
  

  If HOME is not set in environment or in registry:

  git clone https://github.com/syl20bnr/spacemacs $env:APPDATA/.emacs.d
  

If you do have an existing Emacs configuration, look at the full installation instructions for other options.

Introduction

Spacemacs is a new way of experiencing Emacs -- it's a sophisticated and polished set-up, focused on ergonomics, mnemonics and consistency.

Just clone and launch it, then press the space bar to explore the interactive list of carefully-chosen key bindings. You can also press the home buffer's [?] button for some great first key bindings to try.

Spacemacs can be used naturally by both Emacs and Vim users -- you can even mix the two editing styles. Being able to quickly switch between input styles, makes Spacemacs a great tool for pair-programming.

Spacemacs is currently in beta, and any contributions are very welcome.

Features

• Great documentation: access the Spacemacs documentation with SPC h SPC.
• Beautiful GUI: you'll love the distraction free UI and its functional mode-line.
• Excellent ergonomics: all the key bindings are accessible by pressing the SPC or Alt-m.
• Mnemonic key bindings: commands have mnemonic prefixes like SPC b for all the buffer commands or SPC p for the project commands.
• Batteries included: discover hundreds of ready-to-use packages nicely organized in configuration layers following a set of [conventions ][CONVENTIONS.org].

Documentation

Comprehensive documentation is available for each layer by pressing SPC h SPC.

You can also check the [general documentation][DOCUMENTATION.org], [quick start guide][QUICK_START.org] and the [FAQ][FAQ.org].

Getting Help

If you need help, ask your questions in the [Gitter Chat][] and a member of the community will help you out.

If you prefer IRC, connect to the [Gitter Chat IRC server][] and join the #syl20bnr/spacemacs channel.

Last but not least there are a lot of high class tutorials available on YouTube:

• Jack of Some's [Spacemacs tutorial videos][jack-of-some].
• GDQuest's [Game Design oriented tutorials ][gdquest] to Spacemacs.
• Practicalli's [Clojure tutorials based on Spacemacs][practicalli].
• Eivind Fonn's classic [Spacemacs ABC][eivind-fonn].

Prerequisites

1. A package manager if the OS doesn't have one already.

2. Spacemacs is an extension of a popular text editor called [Emacs][GNU Emacs]. So you'll need Emacs installed first.

   Spacemacs requires Emacs 28.2 or above. The development version of Emacs is not officially supported, but it should nevertheless be expected to work.

3. [git][Git] is required to download and update Spacemacs.

4. Tar, in particular [GNU Tar][], is required to install and update Emacs packages used by Spacemacs.

5. (Optional) The default font used by Spacemacs is [Source Code Pro][]. You may customize your own font settings and choose another font. If you want to use this default font, it must be installed.

   Spacemacs also uses fallback fonts to ensure certain Unicode symbols it uses symbols appear correctly. The fonts used are determined by the OS:

   • Linux: [Nanum Gothic][]
   • macOS: [Arial Unicode MS][]
   • Windows: [MS Gothic][] and [Lucida Sans Unicode][]

   If the mode-line doesn't look similar to the picture at the top of this page, make sure you have the correct fallback font installed.

6. (Optional) Various commands in Spacemacs needs one of the following line searching program:

   • [ripgrep (rg)][ripgrep]
   • [The silver searcher (ag)][ag]
   • [ack][]
   • [GNU Grep][] or [BSD Grep][]

   Grep is very slow but it's widely available on most systems and is used as an fallback option.

   We strongly recommend [ripgrep][] over other line searching programs, for its blazing fast speed. The following subsections helps you to install it.

Linux

1. Most Linux distribution ships a package manager already and if this is the case you are all set for this step.

   If it doesn't, you may need to build the softwares mentioned below from their sources.

2. In most distributions, Emacs is installed via an emacs package from the package manager.

   N.B. DO not install [XEmacs][] because it's not supported by Spacemacs. XEmacs is an old fork of Emacs with various [subtle differences][Emacs And XEmacs].

   N.B. Some Linux distributions support only Emacs versions older than 28.2. In this case you should [build it from source][Build Emacs from Source] instead.

3. Very likely Git is already installed on your system. Otherwise, you should be able to install git from your system's package manager.

4. Very likely Tar is already installed on your system. Otherwise, you should be able to install tar from your system's package manager.

5. (Optional) If Nerd Fonts and Nanum Gothic are available from your distribution's package manager, you should install it there.

   Otherwise, the generic way to install it is:

   1. Download the latest pre-built TTF font from https://github.com/adobe-fonts/source-code-pro/releases/latest and https://fonts.google.com/specimen/Nanum+Gothic.

   2. Extract the archive and move the font files to ~/.fonts.

   3. Refresh font cache with:

   fc-cache -fv
   

6. (Optional) If your distribution is listed [here][ripgrep-installation], follow the instructions. Otherwise, you can download its pre-built binary or build it from source.

macOS

1. The most popular package manager on macOS is [Homebrew][], to install it:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

2. Several options exist for installing Emacs on macOS:

   1. [Emacs Plus][] features [additional functionalities][Emacs Plus features] over base Emacs.

      brew tap d12frosted/emacs-plus
      
      # install latest stable release, with Spacemacs icon and native compilation
      brew install emacs-plus --with-spacemacs-icon --with-native-comp
      

      You will require the latest version of Xcode Command Line tools, which can be downloaded from the Apple Developer Portal or by running the following command:

      softwareupdate --all --install --force
      

   2. [Emacs Mac Port][] adds native GUI support to Emacs 28. And the full list of features is available [here][Emacs Mac Port features].

      brew tap railwaycat/emacsmacport
      brew install emacs-mac
      

   3. [Emacs for Mac OS X][] is the binary build of GNU Emacs, without any extra feature.

      brew install --cask emacs
      

3. To install git:

   brew install git
   

4. macOS ships with [BSD Tar][], but there are reports of weird issues so we require [GNU Tar][] instead.

   brew install gnu-tar
   

5. (Optional) To install Source Code Pro Font:

   brew tap homebrew/cask-fonts
   brew install --cask font-source-code-pro
   

   Arial Unicode MS is shipped with macOS v10.5 and later so you don't need to install it manually.

6. (Optional) You can install ripgrep via Homebrew:

   brew install ripgrep
   

Windows

We recommend using wsl2 with wslg support especially with a pgtk build of emacs and wayland. For the installation please refer to the linux installation section. When running emacs within your wsl2 environment emacs will be handled like any other windows application.

If this is not possible you can fallback to a native windows installation, however note that this will create a lot of subtle bugs especially with tls which we will most likely not be able to help with.

If you need to follow that path we recommend to at least use a package manager like [Scoop][] to install the needed packages.

1. You can install [Scoop][] via PowerShell:

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser # Optional: Needed to run a remote script the first time
   irm get.scoop.sh | iex
   

2. Emacs can be installed in PowerShell:

   scoop bucket add extras
   scoop install emacs
   

3. To install git in PowerShell:

   scoop bucket add main
   scoop install git
   

4. Windows 10 build 17063 and later ships with [BSD Tar][], but it's required to install [GNU Tar][] instead to avoid possible issues. Alternatively, if you are running an earlier version of Windows, Tar isn't installed. In either case, you can install GNU Tar via:

   scoop bucket add main
   scoop install tar
   

5. To install Source Code Pro Font in PowerShell:

   scoop bucket add KnotUntied_scoop-fonts https://github.com/KnotUntied/scoop-fonts
   scoop install sourcecodepro
   

   MS Gothic and Lucida Sans Unicode are shipped with Windows 2003 and later so you don't need to install it manually.

6. (Optional) You can install ripgrep in PowerShell:

   scoop bucket add main
   scoop install ripgrep
   

Install

Default Install

1. The default installation downloads Spacemacs to the .emacs.d direc