philosophy
|
for whom?
|
screenshots
|
documentation
|
contribute
|
achievements
|
FAQ
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
.
Documentation
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.
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:
Prerequisites
A package manager if the OS doesn't have one already.
Spacemacs is an extension of a popular text editor called 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.
git is required to download and update Spacemacs.
Tar, in particular GNU Tar, is required to install and update Emacs
packages used by Spacemacs.
(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:
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.
(Optional) Various commands in Spacemacs needs one of the following line
searching program:
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
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.
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.
N.B. Some Linux distributions support only Emacs versions older than
28.2. In this case you should
build it from source instead.
Very likely Git is already installed on your system. Otherwise, you should
be able to install git from your system's package manager.
Very likely Tar is already installed on your system. Otherwise, you should
be able to install tar from your system's package manager.
(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:
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.
Extract the archive and move the font files to ~/.fonts.
Refresh font cache with:
fc-cache -fv
(Optional) If your distribution is listed here,
follow the instructions. Otherwise, you can download its pre-built binary or
build it from source.
macOS
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)"
Several options exist for installing Emacs on macOS:
Emacs Plus features additional functionalities
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
Emacs Mac Port adds native GUI support to Emacs 28. And the full list
of features is available here.
brew tap railwaycat/emacsmacport
brew install emacs-mac
Emacs for Mac OS X is the binary build of GNU Emacs, without any
extra feature.
brew install --cask emacs
To install git:
brew install git
macOS ships with BSD Tar, but there are reports of weird issues so we
require GNU Tar instead.
brew install gnu-tar
(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.
(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.
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
Emacs can be installed in PowerShell:
scoop bucket add extras
scoop install emacs
To install git in PowerShell:
scoop bucket add main
scoop install git
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
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.
(Optional) You can install ripgrep in PowerShell:
scoop bucket add main
scoop install ripgrep
Install
Default Install
The default installation downloads Spacemacs to the .emacs.d directory in
your HOME directory.
But in the case of Windows, HOME is not set out-of-box. We recommend you to
set it as an environment variable, with the same value as environment
variable HOMEPATH, which usually looks like C:\Users\<username>.
Since Spacemacs will now be downloaded at "${HOME}/.emacs.d", if it already
exists it'll be overridden.
Also, if you have either "${HOME}/.emacs.el" or "${HOME}/.emacs", they
will appear before Spacemacs in Emacs's initialization steps. Thus they must
be renamed in order for Spacemacs to load correctly.
To backup/rename the aforementioned files/directory, in shell:
[ -d "${HOME}/.emacs.d" ] && mv "${HOME}/.emacs.d" "${HOME}/.emacs.d.bak"
[ -f "${HOME}/.emacs.el" ] && mv "${HOME}/.emacs.el" "${HOME}/.emacs.el.bak"
[ -f "${HOME}/.emacs" ] && mv "${HOME}/.emacs" "${HOME}/.emacs.bak"
or in PowerShell:
if( Test-Path -Path "${HOME}/.emacs.d" )
{
Rename-Item "${HOME}/.emacs.d" "${HOME}/.emacs.d.bak"
}
if( Test-Path -Path "${HOME}/.emacs.el" )
{
Rename-Item "${HOME}/.emacs.el" "${HOME}/.emacs.el.bak"
}
if( Test-Path -Path "${HOME}/.emacs" )
{
Rename-Item "${HOME}/.emacs" "${HOME}/.emacs.bak"
}
Now clone this repository with Git. The following work for both shell
and PowerShell:
git clone https://github.com/syl20bnr/spacemacs "${HOME}/.emacs.d"
In case you have a limited internet connection or limited speed:
git clone --depth 1 https://github.com/syl20bnr/spacemacs ~/.emacs.d
Now you can launch Emacs and Spacemacs will be loaded.
Alternative Install Location
To install Spacemacs in a different location, we first need to introduce how
Spacemacs is loaded:
When Emacs is started, it looks for the init file
in a deterministic way. The
default installation exploits it by occupying
"${HOME}/.emacs.d/init.el" and let Emacs use it as its init file.
In other word, in default installation, Emacs find and load
"${HOME}/.emacs.d/init.el", which is then responsible to load other files in
"${HOME}/.emacs.d".
If you want to install Spacemacs to a different location, you need to make
sure it's loaded by Emacs in one of its init file.
For example, if you've cloned Spacemacs to "${HOME}/Spacemacs", and if you use
"${HOME}/.emacs.el" as Emacs init file, then the following lines in
"${HOME}/.emacs.el":
;; load Spacemacs's initialization file, "~" is equivalent to "${HOME}"
(load-file "~/Spacemacs/init.el")
First Launch and Configuration
After cloning Spacemacs, the first time when you launch Emacs, Spacemacs will
automatically install the essential packages it requires. This step is the
bootstrap.
Once the bootstrap packages are installed, Spacemacs checks whether you have
an customization file "${HOME}/.spacemacs", known as dotspacemacs:
- If it already exists, Spacemacs loads it as the configuration.
- Otherwise, you need to answer a few questions and Spacemacs will generate
the
dotspacemacs file for you.
If you are new to Emacs and/or Spacemacs, it's fine to just accept the
default choices. They can be changed in the dotspacemacs file later.
Spacemacs will download and install remaining packages it will require,
according to your dotspacemacs. When the all the packages have been
installed, restart Emacs to complete the installation.
dotspacemacs is the configuration file for Spacemacs, it's self
explanatory and is written in Emacs Lisp. Read
general documentation and
quick start guide for more information.
In case you want to store your dotspacemacs at another location, say
under "${HOME}/.spacemacs.d":
- First set the environment variable
SPACEMACSDIR to
"${HOME}/.spacemacs.d".
- Move
"${HOME}/.spacemacs" to "${HOME}/.spacemacs.d/init.el".
In other word, set SPACEMACSDIR to the parent directory of your
dotspacemacs, and move dotspacemacs to the said directory.
Spacemacs logo
For Linux users, create spacemacs.desktop in ~/.local/share/applications/
using this .desktop file as a reference. Change the Name
parameter to Name=Spacemacs and the Icon parameter to
Icon=/PATH/TO/EMACSD/core/banners/img/spacemacs.png where PATH/TO/EMACSD is
the path to your .emacs.d directory, by default ~/.emacs.d.
For macOS users, you need to download the .icns version of the
logo and simply change the logo on the
Dock.
Notes
Depending on the installed version of GnuTLS, securely installing Emacs
packages may fail. If this happens to you please update your OS and Emacs.
If you are behind a company proxy please trust the company firewall cert.
We do not longer support disabling https due to security reasons.
(Windows) If the following error occurs after starting Emacs:
The directory ~/.emacs.d/server is unsafe
Fix it by changing the owner of the directory ~/.emacs.d/server:
- From Properties select the Tab “Security”,
- Select the button “Advanced”,
- Select the Tab “Owner”
- Change the owner to your account name
Source: Stack Overflow
(Windows) The period (dot) before a file or folder name means that it's a
hidden file or folder. To show hidden files and folders:
- Press the Windows key
- Type
File explorer options
- Select the
View tab at the top
- Check
Show hidden files, folders and drives
- Click
OK
Update
Spacemacs relies solely on a rolling update scheme based on the latest
changes available. To update Spacemacs, simply pull the latest
changes from the develop branch:
Close Emacs and update the git repository:
git pull --rebase
Restart Emacs to complete the upgrade.
After updating Spacemacs, you should also
check if any updates are available for your packages. On the Spacemacs Home
Buffer SPC b h, click (press RET) on the [Update Packages] button, or use the convenient keybinding SPC f e U
Upgrading from the deprecated master branch
If you are still on the old master branch (i.e., if
git branch --show-current shows master instead of develop),
you need to upgrade to develop
first.
Quotes
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»
Contributions
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.
Communities
Spacemacs Everywhere
Once you've learned the Spacemacs key bindings, you can use them in other
IDEs/tools, thanks to the following projects:
- Intellimacs - Spacemacs' like key
bindings for IntelliJ platform
- Spaceclipse - Spacemacs’ like key
bindings for Eclipse
- SpaceVim - A community-driven modular
vim distribution
- VSpaceCode - Spacemacs’ like key
bindings for Visual Studio Code
License
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.
Supporting Spacemacs
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 Paypal
badge.
If you used Spacemacs in a project, and you want to show that fact, you can use
the Spacemacs badge: 
For Markdown:
[](https://spacemacs.org)
For HTML:
<a href="https://spacemacs.org"><img alt="Built with Spacemacs" src="https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg" /></a>
For Org-mode:
[[https://spacemacs.org][file:https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg]]
Thank you!
一个由社区驱动的 Emacs 发行版:一套打磨过的、开箱即用的 Emacs 配置,注重人体工学、易记的快捷键和一致性。它目前仍处于 beta 阶段,欢迎参与贡献。