DEV Community 👩‍💻👨‍💻


Posted on • Updated on

How to install AstroNvim without overriding your existing Neovim configuration

I've notice a lot of people out there trying out AstroNvim, and there are a few that want to use it in order to learn about Neovim. I think this is great but... what isn't so great is the installation process taking over your entire Neovim configuration. Wouldn't it be better if you could use AstroNvim for serious work while you slowly create your own Neovim configuration on the side? We can do this. It is possible and I'll tell you how.


Before you go any further make sure you have the latest stable version of Neovim installed. You can download it from the releases page in github.

Also, you need to know how to enter "ex-commands" inside Neovim, we'll be using a lot of those.

The new path

First thing you want to do is decide where you want to install AstroNvim. In order to make this configuration portable I like to use a folder structure similar to what Neovim uses. This way I can get the paths I need by calling Neovim's builtin functions.

So, open Neovim and execute this command.

:echo stdpath('data')
Enter fullscreen mode Exit fullscreen mode

This will show Neovim's data folder. In linux and mac it'll show something like this.

Enter fullscreen mode Exit fullscreen mode

In windows (I believe) it returns this.

Enter fullscreen mode Exit fullscreen mode

We don't want that. Replace nvim with astronvim, like this.

:echo substitute(stdpath('data'), '\(.*\)\zsnvim', 'astronvim', '')
Enter fullscreen mode Exit fullscreen mode

That path, that is where we're going to store (almost) everything related to AstroNvim. Create that folder in your file system.

Next, clone AstroNvim inside the folder you just created, and rename the repository folder to core.

git clone /path/to/astronvim/core
Enter fullscreen mode Exit fullscreen mode

The entrypoint

We can't use AstroNvim's init.lua, we need to make a new one. We have to make sure our personal Neovim configuration doesn't have any conflict with AstroNvim.

This is the part where we create a configuration folder for AstroNvim. Just like before we are going to follow Neovim's pattern. Check where Neovim stores the configuration using :echo stdpath('config'), and then just replace nvim with astronvim.

Inside this config folder you need to create a lua script. You can call it anything you like but for the purpose of this tutorial I will call it entry.lua.

In entry.lua we are going to mess around with a fair amount of variables.

All the code for entry.lua will be in this Github gist.

Define custom directories

local path_sep = vim.loop.os_uname().version:match('Windows') and '\\' or '/'
local join = function(...) return table.concat({...}, path_sep) end
local getpath = function(arg)
  local path = vim.fn.stdpath(arg)
  return vim.fn.substitute(path, [[\(.*\)\zsnvim]], 'astronvim', '')

local data_path = getpath('data')
local astro_config = join(data_path, 'core')
local user_path = getpath('config')
Enter fullscreen mode Exit fullscreen mode

In the first line we figure out what path separator we need. The second line we create a join function so we can create paths using the correct separator. In the third line we use our little stdpath + substitute trick in a function, this will return the paths we need in the new AstroNvim setup.

In data_path we will store everything related to AstroNvim we don't want to manage ourselves. astro_config is the place where we downloaded AstroNvim. And user_path is the directory where we configure AstroNvim.

Setup environment

We are going to do is modify environment variables. Yes. We have to. Changes are only going to take effect in Neovim's process, don't worry. Here's how we do it.

vim.env.XDG_DATA_HOME = data_path
vim.env.XDG_CACHE_HOME = join(data_path, 'cache')
vim.env.XDG_STATE_HOME = join(data_path, 'state')
Enter fullscreen mode Exit fullscreen mode

This will make Neovim change the return value of stdpath, after this it'll point to our custom paths.

Runtime files

Now we go for the runtimepath. This is a Neovim option that specifies what directories it should consider when searching for configuration files. We want to take full control of this, tell Neovim exactly what directories it can use.

vim.opt.runtimepath = {
  join(astro_config, 'after'),
  join(user_path, 'after'),
Enter fullscreen mode Exit fullscreen mode

Our brand new runtimepath will be AstroNvim's config, AstroNvim itself and Neovim's own runtime files.

Plugin directories

We also need to take care of plugins. For this we modify packpath. With this option we tell Neovim where it can find "packages". A package in Neovim is a folder that contains one or more plugins, see :help packages for more details.

vim.opt.packpath = {
  join(data_path, 'nvim', 'site'),
Enter fullscreen mode Exit fullscreen mode

Here the first path is where the plugin manager will download plugins. The second path is our AstroNvim config (just in case you want to add plugins there). Third is where Neovim's first party plugin are.

AstroNvim home

astronvim_installation = {home = astro_config}
Enter fullscreen mode Exit fullscreen mode

With this we make sure the command AstroUpdate can find the path where we downloaded AstroNvim.


The last step. All we have to do now is execute AstroNvim's init.lua.

local execute = loadfile(join(astro_config, 'init.lua'))

if not execute then
  vim.api.nvim_err_writeln("Could not load AstroNvim's init.lua")

Enter fullscreen mode Exit fullscreen mode

A new command

In order to use the new entrypoint I recommend using Neovim with the -u flag.

nvim -u /path/to/astronvim/entry.lua
Enter fullscreen mode Exit fullscreen mode

Assuming you are using bash or zsh as your shell, you can create an alias.

alias code='nvim -u /path/to/astronvim/entry.lua'
Enter fullscreen mode Exit fullscreen mode

Or make a new executable script and add it to your PATH.

#! /usr/bin/env sh

nvim -u /path/to/astronvim/entry.lua "$@"
Enter fullscreen mode Exit fullscreen mode

Either way you should be able to call AstroNvim with this new command, and also call Neovim with just nvim.

How do we customize AstroNvim?

In the same folder where we have entry.lua you create a directory called lua, and inside lua create another folder called user. And then inside user you create a file called init.lua

Inside /path/to/astronvim/lua/user/init.lua you need to create a lua table, add your config and then return that table. Like this.

local user = {plugins = {}}

user.colorscheme = 'tokyonight-night'

user.plugins.init = {

return user
Enter fullscreen mode Exit fullscreen mode

Here I add a new plugin (a colorscheme) and set a new colorscheme.

I highly recommend that you get familiar with the syntax of lua tables. Learn how to create and modify them. It'll make your life so much easier. And don't forget to read AstroNvim's documentation.


This is it. You made it. Now you have the tools to use AstroNvim and also keep your own configuration for Neovim.

Thank you for your time. If you find this article useful and want to support my efforts, consider leaving a tip in buy me a coffee ☕.

buy me a coffee

Top comments (0)

Take a look at this:


Go to your customization settings to nudge your home feed to show content more relevant to your developer experience level. 🛠