- Common
- 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-install
automatically deleted by Spacemacs when it boots? - Environment variables or PATH are not set properly
- How to fix
error: Package 'package-build-' is unavailable
? - How to fix
Warning (bytecomp)
and other compilation warnings? - 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
spacemacs-base
andspacemacs
distributions? - Should I place my settings in
user-init
oruser-config
? - Why do some of my
org
-related settings cause problems? - Why is Spacemacs hanging on startup?
- Why does my color theme not render correctly in terminal mode?
- Typing quickly
fd
takes me out ofinsert 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?
- I want to learn elisp, where do I start ?
- How do I
- Install a package not provided by a layer?
- How to override a layer package?
- 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 and dashes in word motions?
- Setup
$PATH
? - 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
$EDITOR
for git commits? - Try Spacemacs without modifying my existing Emacs configuration?
- Make copy/paste working with the mouse in X11 terminals?
- Use
helm-ag
to search only in files of a certain type? - Modify spacemacs documentation look (space-doc-mode)
- Linux
- Windows
The version is displayed on the upper right corner of the loading screen. You
may also just type SPC f e v
.
It’s space then macs.
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 us 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.
By default Spacemacs will keep only the packages that you use (i.e. the packages
belonging to a layer explicitly listed in the variable
dotspacemacs-configuration-layers
).
To install packages that does not belong to any Spacemacs layers, you can:
- use the variable
dotspacemacs-additional-packages
. - or create a configuration layer configuring the package and add this layer to
dotspacemacs-configuration-layers
- or set the variable
dotspacemacs-install-packages
toused-but-keep-unused
which will prevent Spacemacs from removing the packages you installed manually.
To create a new configuration layer see the quick start guide for more info.
If you use Emacs GUI and don’t launch if from a terminal then edit the
environment variables in the env
file. You can open this file with
SPC f e e
. More information in the Environment variables
section of the
documentation.
This may occur due to heavy network traffic. You can fix it by setting the
dotspacemacs-elpa-timeout
variable to 70
in your dotspacemacs
file.
They are perfectly normal. If you’re curious, you can find out why these occur here.
This is most likely caused by a corrupted package archive. Try deleting your
~/.emacs.d/elpa/archives/
folder and restart Emacs.
Install the default font supported by Spacemacs or choose a fixed width font. More information in the font section of the documentation.
Use the property :separator-scale
of the variable
dotspacemacs-mode-line-theme
. See mode-line section of the documentation for
more details.
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.
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.
The distribution
concept was introduced in 0.104.x. You can now choose between
two distributions spacemacs
or spacemacs-base
. spacemacs-base
contains
only a minimal set of packages; whereas spacemacs
is the full Spacemacs
experience.
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
the layers/
directory.
Any variable that layer configuration code will read and act on must be set
in user-init
, and any variable that Spacemacs explicitly sets but you wish to
override must be set in user-config
.
Anything that isn’t just setting a variable should 99% be in user-config
.
Note that at time of writing files supplied as command line arguments to emacs
will be read before user-config
is executed. (Hence to yield consistent
behaviour, mode hooks should be set in user-init
.)
Since version 0.300, spacemacs uses the org
version from the 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
of the org
shipped with emacs which will induce conflicts. One way to avoid
conflict is to wrap your org
config code in a with-eval-after-load
block
like this:
(with-eval-after-load 'org
;; Org config goes here
;; ....
)
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 .spacemacs
configuration:
(setq tramp-ssh-controlmaster-options
"-o ControlMaster=auto -o ControlPath='tramp.%%C' -o ControlPersist=no")
See issue #3422 and helm issue #1000 for details. If for any reason this code is
not working, you can try to put these settings directly in ~/.ssh/config
:
Host *
ControlMaster auto
ControlPath ~/.ssh/master -%r@%h:%p
ControlPersist = no
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.
This is a feature of Spacemacs, enabling you to easily escape from a lot of
situations, like escaping from insert state
to normal state
.
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 evil-escape
to
dotspacemacs-excluded-packages
in your init file.
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)
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
the ~/.terminfo
yourself.
tic -o ~/.terminfo $TERMINFO/e/eterm-color.ti
Note that eterm-color.ti
may be at a different location, to find out the exact
location you may try to use locate
:
locate eterm-color.ti
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 *Messages*
buffer.
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 PATH
and 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 .profile
, .bash_profile
or .zshenv
, as
opposed to files that are sourced only for interactive shells, such as .bashrc
or .zshrc
. If you are willing to neglect this advice, you may disable the
warning, e.g. from dotspacemacs/user-init
:
(setq exec-path-from-shell-check-startup-files nil)
You can also disable this feature entirely by adding exec-path-from-shell
to
the list dotspacemacs-excluded-packages
if you prefer setting exec-path
yourself.
Very quick start: learn X in Y minutes (where X is elisp)
Practical reference with code examples for various situations that you will encounter: http://caiorss.github.io/Emacs-Elisp-Programming/, more particularly sections Elisp Programming and Elisp code snippets.
Spacemacs provides a variable in the dotspacemacs/layers
function in
.spacemacs
called 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.
To replace a package that is installed and configured by a layer, without
losing the layer’s configuration for that package, add the package to your
dotspacemacs-additional-packages
with the :location
keyword set to the
value local
:
(package-name :location local)
The package should reside at <layer>/local/<package>/
(this could be a
symbolic link to the real package (repo) directory). The package will still
get configured (but not loaded) by the layer. To load the package, require it
from your dotspacemacs/user-config
: (require 'package-name)
. In this way
you can easily switch between the custom version and the version configured by
the layer by commenting in/out the line in dotspacemacs-additional-packages
(to restore deferred loading also comment out the require
form in
dotspacemacs/user-config
).
You could also fully replace (i.e. overwrite) the layer version of the package
by using a Quelpa recipe with the pseudo-fetcher local
as described here and
here.
To completely disable a package and effectively uninstalling it even if it is
part of your used layers, look for the variable dotspacemacs-excluded-packages
in your dotfile and add the package name to it:
(setq-default dotspacemacs-excluded-packages '(package1 package2 ...))
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
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 python-mode
:
(spacemacs|disable-company python-mode)
To change the way spacemacs marks buffers as useless, you can customize
spacemacs-useless-buffers-regexp
which marks buffers matching the regexp as
useless. The variable spacemacs-useful-buffers-regexp
marks buffers matching
the regexp as useful buffers. Both can be customized the same way.
Examples:
;; Only mark helm buffers as useless
(setq spacemacs-useless-buffers-regexp '("\\*helm\.\+\\*"))
;; Marking the *Messages* buffer as useful
(push "\\*Messages\\*" spacemacs-useful-buffers-regexp)
Add the following snippet to your dotspacemacs/user-config
function:
(spacemacs/toggle-visual-line-navigation-globally-on)
You can ensure a mode opens in emacs state by using evil-set-initial-state
.
(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 magit-status-mode
,
(with-eval-after-load 'magit
(define-key magit-status-mode-map
(kbd dotspacemacs-leader-key) spacemacs-default-map))
If you want *
and #
searches to include underscores and dashes as a
part of a word, add (setq-default evil-symbol-word-search t)
to your
dotspacemacs/user-config
.
For other motions, you can modify the syntax table of the mode in question by also adding the following.
;; For python
(add-hook 'python-mode-hook #'(lambda () (modify-syntax-entry ?_ "w")))
;; For ruby
(add-hook 'ruby-mode-hook #'(lambda () (modify-syntax-entry ?_ "w")))
;; For Javascript
(add-hook 'js2-mode-hook #'(lambda () (modify-syntax-entry ?_ "w")))
;; For all programming modes
(add-hook 'prog-mode-hook #'(lambda () (modify-syntax-entry ?_ "w")))
;; For all modes
(add-hook 'after-change-major-mode-hook #'(lambda () (modify-syntax-entry ?_ "w")))
For more details, see the FAQ for Evil.
Some layers require certain tools to be available on your $PATH
. This means
that your $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 $PATH
.
Users of bash
, zsh
, sh
and other similar shells should add following line
to their .bashrc
(.zshrc
, .profile
or your shell’s equivalent). Note that
the export
part is very important.
export PATH=~/.local/bin:$PATH
Users of fish
should add following line to their config.fish
file (should be
in $XDG_CONFIG_HOME
or its default value - ~/.config/fish
). Note that -x
part is very important.
set -x PATH ~/.local/bin $PATH
Users of other shells should consult its documentation on how to setup $PATH
variable (with export to environment).
So now, ~/.local/bin
should be available in your $PATH
. You can verify this
by calling 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 ~/.local/bin
.
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 $PATH
.
In that case you have the option of updating the value of exec-path
in the
dotspacemacs/user-config
function of your .spacemacs
file.
(add-to-list 'exec-path "~/.local/bin/")
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")
To restore the sentence delimiter to two spaces, add the following code to the
dotspacemacs/user-config
function of your .spacemacs
:
(setq sentence-end-double-space t)
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
.spacemacs
:
(fset 'evil-visual-update-x-selection 'ignore)
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 .spacemacs
:
(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.
Spacemacs can be used as the $EDITOR
(or $GIT_EDITOR
) for editing git
commits messages. To enable this you have to add the following line to your
dotspacemacs/user-config
:
(global-git-commit-mode t)
Emacs’s 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 https://github.com/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
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
dotspacemacs/user-config
:
(xterm-mouse-mode -1)
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.el
which are emacs-lisp files. - By using a flag like
--python
which should be self-explaining. The list of available flags could be accessed from terminal with:ag --list-file-types
This is possible because helm-ag
is treating the search input as command-line
arguments of the ag
program.
You can modify the list of visual enhancements applied by the space-doc-mode
:
(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.
Both space-doc-mode
and center-buffer-mode
can be customized
with “Easy Customization Interface”.
If you see the an error message when either Spacemacs is trying to delete an orphaned package, or when you are trying to a package manually:
Package ‘PACKAGE-NAME’ is a system package, not deleting
it means this package comes with your distribution’s package manager and is not installed by
Spacemacs. You can suppress this by adding the package to dotspacemacs-additional-packages
in your .spacemacs
file.
In addition, you also need to add the said package to dotspacemacs-frozen-packages
in your
.spacemacs
, so that you will be able to update your Emacs packages successfully.
The package-quickstart
will collect all the *-autoloads.el
into one file
package-quickstart-file
to speed up the packages loading procedure. After
Spacemacs startup, manually executing the function package-quickstart-refreshe
to generate the package quickstart file, then setting the
dotspacemacs-enable-package-quickstart
to t
, on the next startup, the
Spacemacs will set up packages with loading the package-quickstart-file
, won’t
call the package-initialize
(which will scan package-user-dir
and active
packages one by one).
NOTE: Please enable the load-hints
feature first, otherwise the
package-quickstart-file
addes all the package directories into the load-path
may lead Spacemacs startup slower than no package-quickstartup
feature
enabled.
You can install GDIPP (simplest) or MacType (more complete) on Windows to get very nice looking fonts. It is also recommended to disable smooth scrolling on Windows.
A GUI build of emacs supporting image display is required. You can follow the instructions here. Alternatively you can download binaries of emacs with image support included such as this one.
Check if your Emacs has HTTPS capabilities by doing M-:
and then:
(gnutls-available-p)
If this returns nil
, you need to install the GnuTLS DLL file in the same
directory as Emacs. See here for instructions.
You can follow this explanation explaining how to correct this.
The Spacemacs user maybe feel it’s slow during startup or slow to opening a
*.org
file on Windows system. The root cause is the package manager
(package.el) will add the package directory paths into Emacs’ load-path
seperately, while a Spacemacs-base distribution maybe installes more than 100
packages, and the load-path
will has more than 100 entries with packages
paths on the head, emacs builtin paths on the tail. Then a simple
src_elisp{(require ‘org)} will trigger the emacs walks through the load-path
from the head to the tail to seach org.dll
, org.dll.gz
, org.elc
,
org.elc.gz
, org.el
, org.el.gz
, that will be more than 600 (100*6)
attemptions to open the desired files, but Windows system slow on the open-file
API (Linux/BSD are mutch faster).
The posible solutions are:
- reducing the
load-path
entries by collecting the packages files into one directory and adding this directory to theload-path
, but it needs to rework thepackage.el
to cover adding/updating/removing package in one folder. - constructing a variable
load-hints
to record the files in each package directory'((<pkg1-path> [files]) (<pkg2-path> [files]))
for Searching the file in the list insteads of calling system file API to detect the file existing or not.
Spacemacs implemented the load-hints
feature, controled by the
dotspacemacs-enable-load-hints
, users can set its value to t
to enable
load-hints
feature, then executing the function
spacemacs//package-regenerate-autoloads
and restart the Spacemacs to try this
feature to observer it speedups the Spacemacs or not on the Windows OS.