Getting Started

caution

If you are on AstroNvim v2.0 and are upgrading to AstroNvim v3.0 please see the Migration to v3.0 Page!

AstroNvim is an aesthetic and feature-rich neovim config that is extensible and easy to use with a great set of plugins

⚡ Requirements

• Nerd Fonts (Optional with manual intervention: See Recipes/Customizing Icons)
• Neovim v0.8+ (Not including nightly)
• Tree-sitter CLI (Note: This is only necessary if you want to use auto_install feature with Treesitter)
• A clipboard tool is necessary for the integration with the system clipboard (see :help clipboard-tool for supported solutions)
• Terminal with true color support (for the default theme, otherwise it is dependent on the theme you are using)
• Optional Requirements:
  • ripgrep - live grep telescope search (<leader>fw)
  • lazygit - git ui toggle terminal (<leader>tl or <leader>gg)
  • go DiskUsage() - disk usage toggle terminal (<leader>tu)
  • bottom - process viewer toggle terminal (<leader>tt)
  • Python - python repl toggle terminal (<leader>tp)
  • Node - Node is needed for a lot of the LSPs, and for the node repl toggle terminal (<leader>tn)

info

When using default theme: For MacOS, the default terminal does not have true color support. You will need to use iTerm2 or another terminal emulator that has true color support.

🛠️ Installation

Linux/Mac OS (Unix)

Make a backup of your current nvim folder

mv ~/.config/nvim ~/.config/nvim.bak

Clean neovim folders (Optional but recommended)

mv ~/.local/share/nvim ~/.local/share/nvim.bak
mv ~/.local/state/nvim ~/.local/state/nvim.bak
mv ~/.cache/nvim ~/.cache/nvim.bak

Clone the repository

git clone --depth 1 https://github.com/AstroNvim/AstroNvim ~/.config/nvim
nvim

Windows (PowerShell)

Make a backup of your current nvim folder

Move-Item $env:LOCALAPPDATA\nvim $env:LOCALAPPDATA\nvim.bak

Clean old plugins (Optional but recommended)

Move-Item $env:LOCALAPPDATA\nvim-data $env:LOCALAPPDATA\nvim-data.bak

Clone the repository

git clone --depth 1 https://github.com/AstroNvim/AstroNvim $env:LOCALAPPDATA\nvim
nvim

Docker

If you want to try AstroNvim before installing you can use the following Docker command to open a test instance without touching your current Neovim configuration. This also allows you to use :TSInstall and :LspInstall to load and evaluate language servers and treesitter parsers as well.

docker run -w /root -it --rm alpine:edge sh -uelic '
  apk add bash git lua nodejs npm lazygit bottom python3 go neovim ripgrep alpine-sdk --update
  git clone --depth 1 https://github.com/AstroNvim/AstroNvim ~/.config/nvim
  # Uncomment the line below and replace the link with your user config repo to load a user config
  # git clone https://github.com/username/AstroNvim_user ~/.config/nvim/lua/user
  nvim
'

📦 Setup

Install LSP

Enter :LspInstall followed by the name of the server you want to install

Example: :LspInstall pyright

Install language parser

Enter :TSInstall followed by the name of the language you want to install

Example: :TSInstall python

Install Debugger

Enter :DapInstall followed by the name of the debugger you want to install

Example: :DapInstall python

Manage plugins

Run :Lazy check to check for plugin updates

Run :Lazy update to apply any pending plugin updates

Run :Lazy clean to remove any disabled or unused plugins

Run :Lazy sync to update and clean plugins

Update AstroNvim

Run :AstroUpdate (<leader>pA) to get the latest updates from the repository

Update AstroNvim Packages

Run :AstroUpdatePackages (<leader>pa) to update both Neovim plugins and Mason packages

✨ Features

• Statusline, Winbar, and Tabline with Heirline
• Plugin management with lazy.nvim
• Package management with mason.nvim
• File explorer with Neo-tree
• Autocompletion with Cmp
• Git integration with Gitsigns
• Terminal with Toggleterm
• Fuzzy finding with Telescope
• Syntax highlighting with Treesitter
• Formatting and linting with Null-ls
• Language Server Protocol with Native LSP

⚙️ Configuration

To begin making custom user configurations you must create a user/ folder. We have created a template repository for easily making a user configuration file: Astronvim/user_example

The provided template repo can be used to create a new user configuration repository on your GitHub account or cloned directly. After creating a new repository from the template you can run:

git clone https://github.com/<username>/<config_repo ~/.config/nvim/lua/user