SpaceVim describes itself as "A community-driven modular vim distribution - The ultimate vim configuration". It's an excellent project targeting new or busy Vim users who don't have the time to set up their own configs. It comes with a rich feature set, which provides all the essential tools needed to streamline the workflows of programmers, allowing them to just focus on writing code. I will introduce SpaceVim by offering some practical customization advice and demonstrating a few essential features. However it's not absent of rough edges, which I shall also be informing potential users of.
I first started using Vim back in 2015, and was soon sucked down the
rabbit hole of customizing my
.vimrc. After stumbling across the
Vim plugins ecosystem, it quickly became painfully clear to me that
all attempts to achieve a "perfect" Vim configuration are fantasies.
This is the dilemma SpaceVim aims to resolve. The distribution can be
easily installed on both Linux/macOS and Windows, and fully supports
both Neovim and Vim. My own environment is Neovim on Linux, but the
experience should be comparable for all setups. I'll begin by explaining
how to do basic customizations in SpaceVim, then showcase a couple
useful cool tools, so that newcomers can hit the editor coding!
SpaceVim provides sensible enough defaults that makes it ready for use
straight out-of-the-box. It diverges from the
instead opting for a
~/.Spacevim.d/init.toml config file, which is
well-suited for doing high-level customizations on top of SpaceVim's
This TOML config can be quickly opened in a new buffer via the
SPC f v d keybinding, where you can set SpaceVim global options and
activate its layers, which are the building blocks of SpaceVim. More
concretely, each SpaceVim layer packages related plugins and configures
them to work together. It also adds a consistent set of keybindings on
top, thereby combining everything into a whole that's greater than the
sum of its parts.
As an example, the git layer makes available both tpope's
vim-fugitive and lambdalisue's
gina.vim git wrappers. It also
bundles in junegunn's gv.vim and
airblade's vim-gitgutter. The
main commands provided by all these plugins are hooked up to mnemonic keybinds
SPC g submenu.
SPC g s opens up a git-status buffer in a new window
split, where you can conveniently stage files and write commit messages.
SPC g d opens a git-diff buffer, where you can review the changes
side-by-side before committing them.
It's also worth noting that SpaceVim's wide array of features and
functionalities are discoverable through its
SPC-leader guide UI, as
you saw from the
SPC g example above. In addition to these utilities
layers like git, autocompletion, debugging, grepping, fuzzy finding,
tags, shell, LSP, etc., there also exists 80+ layers for specific
programming languages providing support for things such as syntax
checking, code formatting, code running and more. The complete list
of available layers can be pulled up with
SPC h l, or by executing
At the time of this writing, there are 124 available layers, with new
ones being added all the time. Also note that all plugins pulled in
by enabled layers are loaded lazily, and can be easily updated with
:SPUpdate. This command also updates SpaceVim itself.
~/.SpaceVim.d/init.toml, there is an
under which all general SpaceVim options should be set. Any key defined
here gets converted to a global vim variable by SpaceVim. So adding the
foo = "hello" creates
g:spacevim_foo with value
SpaceVim scripts look for these
g:spacevim_ prefixed global variables
to configure its various settings.
For example, if you wish to use Shougo's
defx.nvim as your filemanager,
you can set the option
filemanager = "defx" in your TOML. To display
absolute line numbers instead of the default relative ones, set
relativenumber = false. To opt-out of having SpaceVim manage your
CWD, you can set
project_rooter_automatically = false. A good portion
of these general SpaceVim options are listed in the SpaceVim help
unfortunately don't appear to be fully updated. So to get a list of
all global variables used by SpaceVim, you can always do
:let g: and
Layers can come with their own layer-local options. Going back to the earlier example of the git layer, the git wrapper I use is vim-fugitive, but if you prefer lambdalisue's gina.vim, then just add the last line under your enabled git layer.
[[layers]] name = "git" git-plugin = "gina"
It's always worth first checking both SpaceVim's built-in
help manual (
:help spacevim-layers) and the online
documentation for usage info and
options regarding your layer of interest. However as only 104 of 124
available layers are documented online, the most reliable method is
reading the layer's source itself, which can all be found inside
Once SpaceVim's options become insufficient for your customization
needs, or if you wish to migrate without abandoning the gems from
.vimrc, you can supply them to SpaceVim through its hooks
mechanism, which SpaceVim calls its "bootstrap functions". These two
functions can be specified with
[options] section of your
init.toml config like so:
[options] # ... # your other options # ... bootstrap_before = "my_config#before" bootstrap_after = "my_config#after"
bootstrap_before is called prior to the loading of any layers
and plugins, while
bootstrap_after is called after that when the
VimEnter event trigger occurs. In the example above, SpaceVim will
my_config.vim and call its
my_config#after function. This
script should be placed inside your
which SpaceVim has already conveniently added to your
Here is an example of a
my_config#after bootstrap function that sets
some options not available via the TOML config:
function! my_config#after() abort call SpaceVim#logger#info("bootstrap_after called") " log bootstrap_after call set inccommand=nosplit " display result of incremental commands (ex. :%s/patt1/patt2/g) set updatetime=500 " GitGutter uses this as its update interval set formatprg=par " use par for reflowing text lines tnoremap jk <C-\><C-n> " allow jk to exit into normal mode in terminal buffer endfunction
It's also a good place for you to load and configure custom plugins not belonging to any SpaceVim layer. For example:
let g:spacevim_custom_plugins = [ \['tpope/vim-eunuch'], \['tpope/vim-rhubarb'], \['dahu/vimple'], \['AndrewRadev/linediff.vim'], \]
SpaceVim is integrated with many valuable tools, such as debugging, testing, tags, offline documentation, etc. But two features I've personally found to be indispensable are the fuzzy finding and grepping utilities.
Currently, there is a choice of 5 fuzzy finders:
- ctrlp.vim by Kien
- denite.nvim by Shougo
- fzf.vim by Junegunn
- LeaderF by Yggdroot
- unite.vim also by Shougo
What SpaceVim offers on top of these individual plugins is standardized
keybindings. So if you know the SpaceVim keybindings (all discoverable
SPC-leader guide if you recall), then trying out a
different fuzzy finder becomes a trivial one-line change in your TOML
config. For example,
SPC f f opens up a fuzzy finder buffer that
recursively searches for files inside your current active buffer's
SPC p f recursively searches from your project's root.
SPC b b will do the same, but through your list of all loaded
SpaceVim also has great support for grepping with tools like
FlyGrep.vim. These utilize
the power of your existing system grepping tools (such as
ack or just plain old
grep) to search through your entire project
directory for occurrences of whatever query pattern you've specified.
vim-grepper presents its search results in a quickfix buffer.
While FlyGrep dynamically updates its matches as you narrow down your query.
I've made the case for the viability of SpaceVim as your vim config.
However as alluded to earlier in the introduction, it's not without some
rough edges. With the project being 2+ years old and many thousands of
users, SpaceVim's core layers and support for popular languages like
hiccups (though mostly minor) do become more apparent as you explore
its more niche features, and use it for less popular languages like
Lua, for which I experienced noticeable delays when working with even
modestly-sized buffers due to performance issues of
workaround is to not use
expr as the method for creating folds).
Furthermore, although it's certainly great to have many choices of tools, it sometimes feels like SpaceVim has spread itself a bit too thin as a result, thereby giving an under-polished user experience with some features. For example, denite was in a broken state for a while due to upstream breaking the API. And while there are many layers, not all are well documented, leaving one to sometimes rely on the source to fully figure out how to configure them.
When it comes to grepping, the different ways vim-grepper and FlyGrep
present their matches (quickfix vs. dynamically updated temp buffer) are
arguably both useful depending on the situation. But making the same case
for having a glut of grepper tools is harder, which is the default state in
SpaceVim. IMO a better UX would be provided by simply using the best grepper
(ripgrep), with perhaps the runner-up
ag, The Silver Searcher)
included as a failsafe. This inconsistency was exacerbated by the fact that
vim-grepper and FlyGrep were originally configured to use different lists of
grepping tools, until I standardized them in a pull request.
Technical details aside, at almost 200 contributors, 1k+ forks and 12k+ stars on GitHub, SpaceVim's extremely active community, spearheaded by its founder Wang Shidong, is arguably the project's greatest strength. The maintainer is proactively opens issues and merges pull requests, and diligently fixes bugs as soon as they appear. He and other knowledgeable members frequently help out users in the various chat channels listed below, which you should definitely check out if you ever find yourself needing assistance.
- SpaceVim/SpaceVim on Gitter
- #spacevim on FreeNode
- t.me/SpaceVim on Telegram
- #spacevim:matrix.org on Matrix
- #spacevim on Slack
- #spacevim on Discord
- SpaceVim on WhatsApp
Note that all messages sent through any one of the above chat platforms are relayed to the rest with a bot, so just pick your favorite.
SpaceVim comes preconfigured and works nicely out-of-the-box. It's modular design is not only a great choice from a development POV, it also allows for convenient high-level customizations.
Although the core and commonly used aspects of the project are quite stable and cohesive, I do believe the project will be even better served by being less accommodating in granting users the freedom to mix-and-match available components and configurations, as it's simply impossible for all combinations of tools and settings to produce optimal development environments. SpaceVim's current paradigm may occasionally lead to minor instabilities and inconsistencies, but if you don't mind venturing off the well-beaten path, nor getting your hands a bit dirty from time to time, then it can still nonetheless be a great option for you.
I wholeheartedly welcome newcomers to SpaceVim as both users and contributors, especially given its welcoming and helpful community, where issues are tackled quickly and PRs merged regularly.