Quick start

Spacemacs divides its configuration into self-contained units called configuration layers. These layers are stacked on top of each other to achieve a custom configuration.

By default Spacemacs uses a dotfile called ~/.spacemacs to control which layers to load. Within this file you can also configure certain features. This design makes it extremely easy to turn Spacemacs into a fully integrated development environment.

For example to get python support, simply add python to the list of dotspacemacs-configuration-layers in your ~/.spacemacs. Find the ~/.spacemacs file by pressing SPC f e d and then after adding the layer, reload it with SPC f e R. Now open a .py file (SPC f f) to find the python environment has been fully configured. Some extra configuration might make the environment even more powerful, which is very well described in the layer's documentation that can be accessed by pressing SPC h l and selecting the python layer entry. For configuration of specific packages within a layer, SPC h SPC provides quick navigation functionality for jumping directly to the relevant location within the configuration files.

A list of pre-configured layers is available here. If you still would like to configure anything not covered by any layer, then it is easy to build a personal layer.

A configuration layer is a directory containing at least a packages.el file which defines and configures packages to be downloaded from Emacs package repositories using the package.el built-in feature of Emacs.

If you already have your own Emacs configuration you can move it to your own layer.

The following command creates a layer in the private directory:

SPC SPC configuration-layer/create-layer RET

Any configuration layers you create must be explicitly loaded in ~/.spacemacs.

Note: For your privacy, the contents of the private directory are not under source control. See the section on private configuration management in the documentation.

As mentioned .spacemacs controls which configuration layers to load and is also a means to customizing Spacemacs.

The following command will create a .spacemacs file in your home directory:

SPC SPC dotspacemacs/install RET

To open the installed dotfile:

SPC f e d

To load some configuration layers using the variable dotspacemacs-configuration-layers:

;; List of configuration layers to load.
dotspacemacs-configuration-layers '(auto-completion smex)

Some configuration layers support configuration variables to expose granular control over layer-specific features, git layer being one such example. Variables can be directly set within dotspacemacs-configuration-layers like so:

;; List of configuration layers to load.
dotspacemacs-configuration-layers '(auto-completion
                                    (git :variables
                                         git-magit-status-fullscreen t)
                                    smex)

At anytime you can apply the changes made to the dotfile or layers without restarting Spacemacs by pressing SPC f e R.

The dotfile template contains further information about how to customize Spacemacs. See the dotfile configuration section of the documentation for more details.

Like Emacs, Spacemacs initialization can also be contained in an init.el file in a special directory ~/.spacemacs.d. The contents of the dotfile should be then copied in the init.el file.

The Emacs dotfile or dotdirectory is not replaced but rather complemented by the Spacemacs dotfile or dotdirectory. During startup, Emacs still uses ~/.emacs.d/init.el (or ~/.emacs) for its initialization, and variable user-emacs-directory will still point to ~/.emacs.d/, even if ~/.spacemacs.d or ~/.spacemacs are present. Only now ~/.emacs.d/init.el is provided by Spacemacs (e.g. after cloning the Spacemacs git repo into an empty ~/.emacs.d/), and your own personal configurations go into ~/.spacemacs.d/init.el (or ~/.spacemacs).

Have a look into the FAQ for an easy workaround to maintain (your former) vanilla Emacs and (your new) Spacemacs configurations side-by-side without the need to rename and backup ~/.emacs.d/.

Some quick how-to's are compiled in the FAQ.