Frequently Asked Questions
- Which version of Spacemacs am I running?
- What is the official pronunciation of Spacemacs?
- Why do you call this a “distribution”, I don’t see any “Spacemacs” executable?
- Why are packages installed with
package-installautomatically deleted by Spacemacs when it boots?
- How to fix package download errors when installing Spacemacs ?
- How to fix
Symbol's value as variable is voiderrors on startup?
- How to fix
(wrong-type-argument arrayp nil)errors on startup?
- The Spacemacs banner is ugly, what should I do?
- The powerline separators are ugly, how can I fix them?
- The powerline separators have no anti-aliasing, what can I do?
- Why is after-init-hook not executed?
- What is the difference between
- Should I place my settings in
- Why do some of my
org-related settings cause problems?
- Why is Spacemacs hanging on startup?
- Why does
SPC SPC) not accept the prefix argument?
- Why does my color theme not render correctly in terminal mode?
- Typing quickly
fdtakes me out of
insert state. What is going on?
- Why do I get files starting with .#?
- Why do I get ‘4m’ characters inside ansi-term?
- Why are my font settings not being respected?
- Why am I getting a message about environment variables on startup?
- How do I:
- Install a package not provided by a layer?
- Disable a package completely?
- Disable a package only for a specific major-mode?
- Disable company for a specific major-mode?
- Change special buffer rules?
- Enable navigation by visual lines?
- Disable evilification of a mode?
- Include underscores in word motions?
- Change or define an alias for a leader key?
- Restore the sentence delimiter to two spaces?
- Prevent the visual selection overriding my system clipboard?
- Make spell-checking support curly quotes (or any other character)?
- Use Spacemacs as the
$EDITORfor git commits?
- Try Spacemacs without modifying my existing Emacs configuration?
- Make copy/paste working with the mouse in X11 terminals?
helm-agto search only in files of a certain type?
- Modify spacemacs documentation look (space-doc-mode)
- Remap paste key to be able to paste copied text multiple times
Which version of Spacemacs am I running?
The version is displayed on the upper right corner of the loading screen. You
may also just type
SPC f e v.
What is the official pronunciation of Spacemacs?
As it is written, that is space then macs.
Why do you call this a “distribution”, I don’t see any “Spacemacs” executable?
Although we could do it we don’t package Emacs with Spacemacs. We allow users to choose whatever build of Emacs they want that works with their OS, this is more flexible and it saves use tons of issues. Spacemacs is more than a configuration of Emacs it comes with advanced feature, concepts and tooling. Roughly, think of it as a Linux distribution where we would ask people to install the kernel first and then fetch somehow the actual code to get the distribution. Note that some Linux distributions may start to create packages for Spacemacs, they are unofficial packages, we will never package Emacs with Spacemacs.
Why are packages installed with
package-install automatically deleted by Spacemacs when it boots?
By default Spacemacs will keep only the packages that you use (i.e. the packages
belonging to a layer explicitly listed in the variable
To install packages that does not belong to any Spacemacs layers, you can:
- use the variable
- or create a configuration layer configuring the package and add this layer to
- or set the variable
used-but-keep-unusedwhich will prevent Spacemacs from removing the packages you installed manually.
To create a new configuration layer see the quick start guide for more info.
How to fix package download errors when installing Spacemacs ?
Since 0.105.0 HTTPS protocol is used by default to download packages. If your
environment does not allow HTTPS to reach ELPA repositories then you can start
Emacs with the
--insecure argument for force the usage of HTTP non secured
protocol. You can set the variable
nil in your
dotfile to remove the need to start Emacs with
How to fix
Symbol's value as variable is void errors on startup?
If Emacs reports an error that the symbol
- is unbound as a
variable, it is probably because you are using HTTPS to download packages, but
you shouldn’t be. Try deleting your packages (the
.emacs.d/elpa folder), and
restart Emacs without HTTPS to download the packages again. There are two ways
to do this:
- Run Emacs with the
--insecurecommand line argument:
emacs --insecure. You will have to do this again the next time you update your packages.
- Set the variable
nilin your dotfile. This has the same effect as
--insecure, but is persistent.
How to fix
(wrong-type-argument arrayp nil) errors on startup?
This is most likely caused by a corrupted package archive. Try deleting your
~/.emacs.d/elpa/archives/ folder and restart Emacs.
The Spacemacs banner is ugly, what should I do?
Install the default font supported by Spacemacs or choose a fixed width font. More information in the font section of the documentation.
The powerline separators are ugly, how can I fix them?
Use the property
:powerline-scale of the variable
See font section of the documentation for more details.
The powerline separators have no anti-aliasing, what can I do?
Emacs powerline uses XMP images to draw the separators in a graphical
environment. You can have anti-aliasing if you use the
utf8 separator. Note
that by default the
utf8 separator is used in a terminal. See the powerline
section in the font section of the documentation.
Why is after-init-hook not executed?
Don’t launch Spacemacs with
emacs -q -l init.el command. This command will run
the hooked functions in
after-init-hook before the evaluation of the passed
-l init.el file.
What is the difference between
distribution concept was introduced in 0.104.x. You can now choose between
only a minimal set of packages; whereas
spacemacs is the full Spacemacs
Set the distribution with
dotspacemacs-distribution variable. The default is
spacemacs. For more information as to what is included, check out the
packages.el file in the respective folders in the
+distributions folder of
Should I place my settings in
Any variable that layer configuration code will read and act on must be set
user-init, and any variable that Spacemacs explicitly sets but you wish to
override must be set in
Anything that isn’t just setting a variable should 99% be in
Why do some of my
org-related settings cause problems?
Since version 0.104, spacemacs uses the
org version from the org ELPA
repository instead of the one shipped with emacs. Then, any
org related code
should not be loaded before
dotspacemacs/user-config, otherwise both versions
will be loaded and will conflict.
Because of autoloading, calling to
org functions will trigger the loading up
org shipped with emacs wich will induce conflicts. One way to avoid
conflict is to wrap your
org config code in a
(with-eval-after-load 'org ;; here goes your Org config :) ;; .... )
Why is Spacemacs hanging on startup?
This is probably related to Helm using Tramp which tries to figure out some SSH/DNS settings at startup. The root cause is probably your ISP redirecting non-existing addresses to their own servers.
Try using these settings in the
user-init function in your
(setq tramp-ssh-controlmaster-options "-o ControlMaster=auto -o ControlPath='tramp.%%C' -o ControlPersist=no")
Host * ControlMaster auto ControlPath ~/.ssh/master -%r@%h:%p ControlPersist = no
SPC SPC) not accept the prefix argument?
If you try to run
helm-M-x with the prefix argument (i.e.
SPC u SPC SPC) it
will fail with this message:
helm-M-x first, select the command you want to run, and press
C-u before pressing
RETURN. For instance:
SPC SPC org-reload C-u RET
Why does my color theme not render correctly in terminal mode?
In the terminal version of Emacs, color themes will not render correctly as colors are rendered by the terminal and not by emacs. You will probably have to change your terminal color palette. More explanations can be found on emacs-color-theme-solarized webpage.
fd takes me out of
insert state. What is going on?
This is a feature of Spacemacs, enabling you to easily escape from a lot of
situations, like escaping from
insert state to
The sequence of characters used can be customized. See the documentation for more information.
If you don’t like this feature, you can deactivate it by adding
dotspacemacs-excluded-packages in your init file.
Why do I get files starting with .#?
These are lockfiles, created by Emacs to prevent editing conflicts which occur when the same file is edited simultaneously by two different programs. To disable this behaviour:
(setq create-lockfiles nil)
Why do I get ‘4m’ characters inside ansi-term?
Ansi-term only has a subset of capabilities supported by xterm256. Your shell
(e.g. fish shell) might ignore
$TERMINFO information and require you to set
tic -o ~/.terminfo $TERMINFO/e/eterm-color.ti
eterm-color.ti may be at a different location, to find out the exact
location you may try to use
Why are my font settings not being respected?
The settings of
dotspacemacs-default-font (such as size, weight, etc.) will
only be applied if the name of the font exists on your system. Check to make
sure that this is the case. If Spacemacs can’t find the font, there should be a
warning to this effect in the
Why am I getting a message about environment variables on startup?
Spacemacs uses the
exec-path-from-shell package to set the executable path
when Emacs starts up. This is done by launching a shell and reading the values
of variables such as
MANPATH from it. If your shell configuration
sets the values of these variables inconsistently, this could be problematic. It
is recommended to set such variables in shell configuration files that are
sourced unconditionally, such as
opposed to files that are sourced only for interactive shells, such as
.zshrc. If you are willing to neglect this advice, you may disable the
warning, e.g. from
(setq exec-path-from-shell-check-startup-files nil)
You can also disable this feature entirely by adding
dotspacemacs-excluded-packages if you prefer setting
How do I:
Install a package not provided by a layer?
Spacemacs provides a variable in the
dotspacemacs/layers function in
dotspacemacs-additional-packages. Just add a package name
to the list and it will be installed when you reload your configuration with
SPC f e R, or at the next Spacemacs launch.
Disable a package completely?
To completely disable a package and effectively uninstalling it even if it is
part of your used layers, look for the variable
in your dotfile and add the package name to it:
(setq-default dotspacemacs-excluded-packages '(package1 package2 ...))
Disable a package only for a specific major-mode?
This is done by removing the hook added by Spacemacs. For example to remove
flycheck support in python buffers, look for the function
dotspacemacs/user-config in your dotfile and add the following code:
(remove-hook 'python-mode-hook 'flycheck-mode)
Hint to know the name of the major-mode of the current buffer press:
SPC h d
v major-mode RET
Disable company for a specific major-mode?
It may be handy to disable
company for a given mode if you plan on configuring
auto-complete instead. One easy way to do it is to use the macro
spacemacs|disable-company in the function
dotspacemacs/user-config of your
dotfile. The following snippet disables company for
To change the way spacemacs marks buffers as useless, you can customize Change special buffer rules?
spacemacs-useless-buffers-regexpwhich marks buffers matching the regexp as useless. The variable
spacemacs-useful-buffers-regexpmarks buffers matching the regexp as useful buffers. Both can be customized the same way.
;; Only mark helm buffers as useless (setq spacemacs-useless-buffers-regexp '("\\*helm\.\+\\*")) ;; Marking the *Messages* buffer as useful (push "\\*Messages\\*" spacemacs-useful-buffers-regexp)
Enable navigation by visual lines?
Add the following snippet to your
;; Make evil-mode up/down operate in screen lines instead of logical lines (define-key evil-motion-state-map "j" 'evil-next-visual-line) (define-key evil-motion-state-map "k" 'evil-previous-visual-line) ;; Also in visual mode (define-key evil-visual-state-map "j" 'evil-next-visual-line) (define-key evil-visual-state-map "k" 'evil-previous-visual-line)
Disable evilification of a mode?
You can ensure a mode opens in emacs state by using
(evil-set-initial-state 'magit-status-mode 'emacs)
You can also do this using buffer name regular expressions. E.g. for magit, which has a number of different major modes, you can catch them all with
(push '("*magit" . emacs) evil-buffer-regexps)
This should make all original magit bindings work in the major modes in
question. To enable the leader key in this case, you may have to define a
binding in the mode’s map, e.g. for
(with-eval-after-load 'magit (define-key magit-status-mode-map (kbd dotspacemacs-leader-key) spacemacs-default-map))
Include underscores in word motions?
You can modify the syntax table of the mode in question. To do so you can
include this on your
Some layers require certain tools to be available on your
$PATH. This means
$PATH must contain the installation paths for those tools. For
example, if you have installed some tools to
~/.local/bin and want them to be
available in Spacemacs, you need to add
~/.local/bin to your
sh and other similar shells should add following line
.profile or your shell’s equivalent). Note that
export part is very important.
fish should add following line to their
config.fish file (should be
$XDG_CONFIG_HOME or its default value -
~/.config/fish). Note that
part is very important.
set -x PATH ~/.local/bin $PATH
Users of other shells should consult its documentation on how to setup
variable (with export to environment).
~/.local/bin should be available in your
$PATH. You can verify this
echo $PATH. But you also should verify that
$PATH is set properly
in your environment. To do so call following command in your terminal.
env | grep "PATH"
This is the value that will be used by Emacs. So it must contain
After that you can run Spacemacs and check that it properly gets the value of
$PATH by running
M-: (getenv "PATH").
Note that having
~/.local/bin in your
$PATH also means that it’s possible to
run terminal and call tools from
~/.local/bin without specifying their full
path. Under certain conditions you might want to avoid modifying your
In that case you have the option of updating the value of
exec-path in the
dotspacemacs/user-config function of your
(add-to-list 'exec-path "~/.local/bin/")
Change or define an alias for a leader key?
It is possible to change a leader key by binding its keymap to another sequence.
For instance, if you want to switch
SPC S (spelling) with
SPC d (used by
dash) to make the former easier to reach, you can use:
(defun dear-leader/swap-keys (key1 key2) (let ((map1 (lookup-key spacemacs-default-map key1)) (map2 (lookup-key spacemacs-default-map key2))) (spacemacs/set-leader-keys key1 map2 key2 map1))) (dear-leader/swap-keys "S" "d")
If you want to define your own alias, like using
SPC é (because it’s a not
used key on your keyboard-layout for instance) for accessing
SPC w (windows
management), you can use this:
(defun dear-leader/alias-of (key1 key2) (let ((map (lookup-key spacemacs-default-map key2))) (spacemacs/set-leader-keys key1 map))) (dear-leader/alias-of "é" "w")
Restore the sentence delimiter to two spaces?
To restore the sentence delimiter to two spaces, add the following code to the
dotspacemacs/user-init function of your
(setq sentence-end-double-space t)
Prevent the visual selection overriding my system clipboard?
On some operating systems, there is only one clipboard for both copied and
selected texts. This has the consequence that visual selection – which
should normally be saved to the PRIMARY clipboard – overrides the SYSTEM
clipboard, where normally goes the copied text. This can be corrected by
adding the following code to the
dotspacemacs/user-config of your
(fset 'evil-visual-update-x-selection 'ignore)
Make spell-checking support curly quotes (or any other character)?
To have spell-checking support curly quotes (or any other character), you need
to add a new entry to
ispell-local-dictionary-alist, by adding for example the
following code in the
dotspacemacs/user-config of your
(add-to-list 'ispell-local-dictionary-alist (quote ("my_english" "[[:alpha:]]" "[^[:alpha:]]" "['’]" t ("-d" "en_US") nil utf-8)))
You can then add any regular expression you want in the fourth argument (i.e.
add a symbol within
['’]) to make it supported. Consult the help of
ispell-dictionary-alist for more details about the possibilities.
You finally have to set
my_english as your
ispell-local-dictionary in order
to use the dictionary supporting your newly added characters.
Use Spacemacs as the
$EDITOR for git commits?
Spacemacs can be used as the
$GIT_EDITOR) for editing git
commits messages. To enable this you have to add the following line to your
Try Spacemacs without modifying my existing Emacs configuration?
Emacs’ ability to use any directory as the home for launching it allows us to
try out Spacemacs (or any other Emacs configuration we desire) without having to
go through the trouble of backing up our
~/.emacs.d directory and then cloning
the new configuration. This can be achieved easily using the following steps:
mkdir ~/spacemacs git clone firstname.lastname@example.org:syl20bnr/spacemacs.git ~/spacemacs/.emacs.d HOME=~/spacemacs emacs
If you’re on Fish shell, you will need to modify the last command to:
env HOME=$HOME/spacemacs emacs
Make copy/paste working with the mouse in X11 terminals?
It is possible to disable the mouse support in X11 terminals in order to
enable copying/pasting with the mouse. You need to add this line to your
helm-ag to search only in files of a certain type?
It is possible to restrict the scope of
helm-ag to search only expressions in
some specified file types. There are two ways of doing this, both by appending
some expressions to the search input:
- By using a regexp with
-G, for instance
-G\.el$will look for all files ending with
.elwhich are emacs-lisp files.
- By using a flag like
--pythonwhich should be self-explaining. The list of available flags colud be accessed from terminal with:
This is possible because
helm-ag is treating the search input as command-line
arguments of the
Modify spacemacs documentation look (space-doc-mode)
You can modify the list of visual enhancements applied by the
(setq spacemacs-space-doc-modificators '(center-buffer-mode org-indent-mode view-mode hide-line-numbers alternative-emphasis alternative-tags-look link-protocol org-block-line-face-remap org-kbd-face-remap resize-inline-images))
By default only
center-buffer-mode is disabled.
center-buffer-mode can be customized
with “Easy Customization Interface”.
Remap paste key to be able to paste copied text multiple times
In vim and evil, pasting over a text would cause it to be copied, hence making it impossible to paste the same text multiple times.
To fix this, add the following snippet to your
(defun evil-paste-after-from-0 () (interactive) (let ((evil-this-register ?0)) (call-interactively 'evil-paste-after))) (define-key evil-visual-state-map "p" 'evil-paste-after-from-0)
Why do the fonts look crappy on Windows?
Why is there no Spacemacs logo in the startup buffer?
Why are all packages unavailable?
Check if your Emacs has HTTPS capabilities by doing
M-: and then:
If this returns
nil, you need to install the GnuTLS DLL file in the same
directory as Emacs. See here for instructions.
The powerline isn’t shown correctly when Spacemacs is used within
You can follow this explanation explaining how to correct this.