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.
- Great documentation: access the Spacemacs documentation with
SPC h SPC.
- Beautiful GUI: you'll love the distraction free UI and its functional
- Excellent ergonomics: all the key bindings are accessible by pressing the
space bar or alt-m.
- Mnemonic key bindings: commands have mnemonic prefixes like
SPC b for all the buffer commands or SPC p for the project
- Batteries included: discover hundreds of ready-to-use packages nicely
organised in configuration layers following a set of
Comprehensive documentation is available for each layer by pressing
SPC h SPC.
You can also check the general documentation,
quick start guide and the FAQ.
If you need help, ask your question 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
Spacemacs is an extension of a popular text editor called Emacs. Thus you need
to first install base Emacs and then download the Spacemacs extension files with
Spacemacs requires Emacs 25.1 or above. The development version of Emacs is not
officially supported, but it should nevertheless be expected to work.
Some modes require third-party tools that you'll have to install via your
favorite package manager.
emacs package with your linux distributions package manager.
Do not install the
xemacs package. It's not supported by Spacemacs. XEmacs is
an old fork of Emacs. The X in its name is unrelated to X11.
Emacs has graphical support.
Note: The Ubuntu LTS 12.04 and 14.04 repositories only have Emacs version
24.3 available. Version 25.1 or greater needs to be built from source.
This might also be true for other linux distributions.
brew tap d12frosted/emacs-plus
brew install emacs-plus
ln -s /usr/local/Cellar/emacs-plus/*/Emacs.app/ /Applications/
brew tap railwaycat/emacsmacport
brew install emacs-mac
Copy and paste the symlink (
ln) from the install instructions if
Homebrew now recommends to use the cask version with the following message:
"Please try the Cask for a better-supported Cocoa version". To install the cask
brew cask install emacs
This installs a pre-built package from https://emacsformacosx.com/
If you're not comfortable with the ways mentioned above, then
EmacsWiki lists down
a few ways to install Emacs for Mac OS.
Install Source Code Pro font
Once Emacs is installed, run the following commands in the terminal to install
the default Source Code Pro font:
brew tap caskroom/fonts
brew cask install font-source-code-pro
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d
After completing the Spacemacs install process, then it's also
recommended to add the osx layer to your dotfile. Installation
instructions are available in the documentation for the osx layer.
You can download good quality builds from the emacs-w64 project.
It is recommended to install the most recent stable build.
You'll also need
gzip and put it in your path, to download it go to the
GNUWin32 project page
Be sure to declare an environment variable named
HOME that's pointing to your
C:\Users\<username>. Then you can clone Spacemacs into that
Sometimes you'll get the following error when you first start Emacs:
The directory ~/.emacs.d/server is unsafe
To fix it change the owner of the directory
- from Properties select the Tab “Security”,
- select the button “Advanced”,
- select the Tab “Owner”
- change the owner to your account name
Source: Stack Overflow
For efficient searches we recommend installing
pt (the platinum searcher).
pt version 1.7.7 or higher is required.
If you have an existing Emacs configuration, back it up first by running the
following code in your terminal:
mv .emacs.d .emacs.d.bak
mv .emacs .emacs.bak
Don't forget to backup and remove the
~/.emacs file. Otherwise Spacemacs
WILL NOT be able to load. Because that file prevents Emacs from loading
the proper initialization file.
Clone the repository with Git:
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'll handle updates
Note for Windows users
If you use windows, then you'll have to modify the git command by inserting
the correct path to your
.emacs.d folder. The dot before the folder means
that it's hidden. You'll have to search for hidden files to find the folder.
When you have found the folder, substitute the original path with the correct
one. The proper code would look something like this:
git clone https://github.com/syl20bnr/spacemacs /path/to/your/.emacs.d
Install the default fonts
It's recommended to install Source Code Pro by Adobe, as the default
font. It ensures that, for example the symbols on the modeline (bottom bar)
looks correct. It's also recommended to use a "Fallback font". These
depend on the system:
- GNU/Linux: NanumGothic (package named fonts-nanum on Debian, for
- macOS: Arial Unicode MS
- Windows: MS Gothic or Lucida Sans Unicode
If the modeline doesn't look similar to the
picture at the top of this page, then make sure you have the
correct fallback font installed.
If you're running in a terminal then you'll also need to change the terminals
Launch Emacs, and answer the questions in the Dotfile wizard installer. If
you are new to Emacs and Spacemacs, then it's fine to just accept the default
choices. It's easy to try the other choices later, without having to
reinstall Spacemacs. They can be changed in the dotfile
After answering the questions, then Spacemacs starts downloading and
installing the packages it requires. When the packages have been installed.
Restart Emacs to complete the installation.
If you get an error regarding package downloads, then you can try to
disable the HTTPS protocol by starting Emacs with the
Or you can set the
dotspacemacs-elpa-https variable to
nil in your
~/.spacemacs. That will remove the need to start Emacs with the
--insecure argument. You may also want to clear out your
directory before doing this, so that any corrupted packages you may have
downloaded will be re-installed.
error: Package 'package-build-' is unavailable may occur due to heavy network
taffic. You can fix it by setting the
dotspacemacs-elpa-timeout variable to
70 in your dotfile.
Warning (bytecomp) and other compilation warnings are perfectly normal. If
you're curious, you can find out why these occur here.
If the mode-line turns red then be sure to consult the FAQ.
There are currently, two supported, alternative locations, for a Spacemacs
Modify HOME environment variable
This solution is ideal for quickly trying Spacemacs without compromising your
existing configuration. Clone Spacemacs outside the Emacs dotdirectory
~/.emacs.d and modify the HOME environment variable.
git clone https://github.com/syl20bnr/spacemacs.git ~/spacemacs/.emacs.d
Note: If you're using the Fish shell, then you'll need to modify the last
env HOME=$HOME/spacemacs emacs
Modify spacemacs-start-directory variable
This solution is better suited to "embed" Spacemacs into your own configuration.
If you've cloned Spacemacs into
~/.emacs.d/spacemacs/, then drop the following
lines in the
(setq spacemacs-start-directory "~/.emacs.d/spacemacs/")
(load-file (concat spacemacs-start-directory "init.el"))
For Ubuntu users, follow this guide to
change the logo in Unity.
For Mac users, you need to download the .icns version of the logo,
then change the logo on the Dock.
Spacemacs shows a notification when a new version is available (only when you
are on the default
master branch). If you are on the
develop branch then
you'll have to update the Spacemacs repository manually.
Automatic update (on master branch)
When a new version is available then a little arrow appears in the mode-line.
Its color depends on the number of versions that have been released since your
last update. Green means that you have a recent version, orange and red means
that you have an older version.
Manual update (on master branch)
> angle brackets when you're typing the lines below into
your shell. And replace the text: "tag version which you are updating to" with a
tagged version. This page lists the latest tags
git reset --hard <tag version which you are updating to>
On develop branch
Close Emacs and update the git repository:
Restart Emacs to complete the upgrade.
Revert to a specific version
To revert to a specific version, just checkout the corresponding branch. For
instance to revert to version
0.200, type the following command:
git checkout origin/release-0.200
After updating Spacemacs (either manually or automatically), then you also
should check if any updates are available for your packages. On the Spacemacs
SPC b h, click (press
RET) on the
[Update Packages] button.
Quote by ashnur:
«I feel that spacemacs is an aircraft carrier and I am playing table tennis
on the deck as a freerider.»
Quote by deuill:
«I LOVE SPACEMACS AND MAGIT
That is all»
Spacemacs is a community-driven project, it needs you to keep it up to date
and to propose great and useful configurations for all the things!
Before contributing be sure to consult the
contribution guidelines and conventions.
Here is a throughput graph of the repository for the last few weeks:
The license is GPLv3 for all parts specific to Spacemacs, this includes:
- the initialization and core files
- all the layer files
- the documentation
For the packages shipped in this repository, you can refer to the files header.
Spacemacs logo by Nasser Alshammari released under a
Creative Commons Attribution-ShareAlike 4.0 International License.
The best way to support Spacemacs is to contribute to it either by reporting
bugs, helping the community on the Gitter Chat or sending pull requests.
You can show your love for the project by getting cool Spacemacs t-shirts, mugs
and more in the Spacemacs Shop.
If you want to show your support financially, then you can contribute to
Bountysource, or buy a drink for the maintainer by clicking on the
If you used spacemacs in a project, and you want to show that fact, you can use
the spacemacs badge: