Introduction

Spacemacs is a new way to experience Emacs -- a sophisticated and
polished set-up focused on ergonomics, mnemonics and consistency.

Just clone it, 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. Switching easily between input styles
makes Spacemacs a great tool for pair-programming.

Prerequisites

Emacs

Spacemacs is operational with Emacs 24.3, but Emacs 24.4 and above are highly
recommended to enjoy a full experience. The next Emacs major release, Emacs 25,
is not officially supported but is partially working (i.e. bugs should be
expected).

Linux distros

You should install the "emacs" package, not the "xemacs" package.
XEmacs is an old fork of Emacs. The X in its name is unrelated to X11.
Both Emacs and XEmacs have graphical support.

Note: Ubuntu LTS 12.04 and 14.04 repositories have only Emacs 24.3
available. You are advised to build from source Emacs 24.4 or greater, as most packages require
this version. The same may be true for other distributions as well.

OS X

Please note: these homebrew commands will install Emacs, and link it to your
/Applications directory. You still need to run the git clone mentioned at
the start of this file. That will populate your ~/.emacs.d directory, which
is what transforms a regular Emacs into Spacemacs.

Note that the emacs-mac-port server behaves differently than the regular Emacs
server which in particular DOES NOT allow multi-tty if you start GUI i.e.
you can't connect to the Emacs GUI server with emacsclient but server-client
works if you start from terminal(TTY-only).
Details can be found on the emacs-mac-port README.

Windows

Good quality builds can be found on this page. It is
recommended to install the most stable build.

Be sure to declare a environment variable named HOME pointing to your user
directory C:\Users\<username>. Then you can clone Spacemacs in this directory.

For efficient searches we recommend to install pt (the platinum searcher).
pt version 1.7.7 or higher is required.

Install

Default installation

If you have an existing Emacs configuration, back it up first:

cd~
mv .emacs.d .emacs.d.bak
mv .emacs .emacs.bak

Don't forget to backup and remove~/.emacs file otherwise Spacemacs
WILL NOT load since that file prevents Emacs from loading the proper
initialization file.

Clone the repository:

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

master is the stable branch and it is immutable, DO NOT make any
modification to it or you will break the update mechanism. If you want to
fork Spacemacs safely use the develop branch where you handle the update
manually.

Launch Emacs. Spacemacs will automatically install the packages it requires.
If you get an error regarding package downloads then you may try to disable
the HTTPS protocol by starting Emacs with

emacs --insecure

You may wish to clear out your .emacs.d/elpa directory before doing this,
so that any corrupted packages you may have downloaded will be reinstalled.

Restart Emacs to complete the installation.

If the mode-line turns red then be sure to visit the
troubleshooting guide and consult the FAQ.

Installation alongside another configuration

To try out Spacemacs (or any other Emacs configuration you desire) without
having to go through the trouble of backing up you ~/.emacs.d directory and
then cloning the new configuration: