Skip to main content

​
Prerequisites

Before installing nvim-treesitter, verify you have the required dependencies.

​
Neovim version

Check your Neovim version: 
nvim --version
You need Neovim 0.11.0 or later. The plugin supports:
Older versions are not supported. Compatibility with Neovim 0.X is typically removed after the release of Neovim 0.(X+1).1.

​
System dependencies

Install these tools on your system: 
sudo apt install tar curl build-essential
cargo install tree-sitter-cli
tree-sitter-cli version 0.26.1 or later is required. Check with tree-sitter --version.

​
Install the plugin

Choose your package manager below: Add to your ~/.config/nvim/lua/plugins/treesitter.lua: 
return {
  'nvim-treesitter/nvim-treesitter',
  lazy = false,
  build = ':TSUpdate',
}
The build = ':TSUpdate' option automatically updates parsers when the plugin is installed or updated.
For more control, you can configure installation in the spec: 
return {
  'nvim-treesitter/nvim-treesitter',
  lazy = false,
  build = ':TSUpdate',
  config = function()
    -- Optional: configure installation directory
    require('nvim-treesitter').setup({
      install_dir = vim.fn.stdpath('data') .. '/site',
    })
    
    -- Install your preferred parsers
    require('nvim-treesitter').install({ 'lua', 'vim', 'vimdoc' })
  end,
}

​
packer.nvim

Add to your ~/.config/nvim/lua/plugins.lua: 
use {
  'nvim-treesitter/nvim-treesitter',
  run = function()
    require('nvim-treesitter.install').update({ with_sync = true })
  end,
}

​
rocks.nvim

Install from the command line: 
:Rocks install nvim-treesitter
Then in your config: 
require('nvim-treesitter').install({ 'lua', 'python', 'rust' })

​
vim-plug

Add to your ~/.config/nvim/init.vim or ~/.vimrc: 
Plug 'nvim-treesitter/nvim-treesitter', {'do': ':TSUpdate'}
Or in init.lua: 
vim.cmd [[
  Plug 'nvim-treesitter/nvim-treesitter', {'do': ':TSUpdate'}
]]

​
Native packages

Neovim has built-in package management: 
mkdir -p ~/.local/share/nvim/site/pack/plugins/start
cd ~/.local/share/nvim/site/pack/plugins/start
git clone https://github.com/nvim-treesitter/nvim-treesitter.git
Then in Neovim: 
:TSUpdate
Do not lazy-load nvim-treesitter. The plugin must load at startup to properly register parsers on the runtimepath.

​
Configuration

Call setup() to customize installation options: 
require('nvim-treesitter').setup({
  -- Directory to install parsers and queries to
  -- Defaults to stdpath('data')/site
  install_dir = vim.fn.stdpath('data') .. '/site',
})
You do not need to call setup() for nvim-treesitter to work with default values. Only call it if you want to customize the installation directory.
The install_dir is prepended to your runtimepath to give installed parsers priority over other sources.

​
Installing parsers

​
Via commands

The most straightforward way is using commands: 
:TSInstall rust javascript python
Available options:
  • :TSInstall <language> - Install specific language parser(s)
  • :TSInstall! - Force reinstall even if already installed
  • :TSInstall stable - Install all stable tier parsers
  • :TSInstall unstable - Install all unstable tier parsers (not recommended)

​
Via Lua API

In your init.lua: 
-- Asynchronous installation (non-blocking)
require('nvim-treesitter').install({ 'rust', 'javascript', 'python' })

-- Synchronous installation (blocks until complete)
require('nvim-treesitter').install({ 'rust', 'javascript', 'python' }):wait(300000)
The install() function accepts options: 
require('nvim-treesitter').install({ 'rust', 'go' }, {
  force = true,         -- Reinstall even if already present
  generate = false,     -- Generate parser.c from grammar
  max_jobs = 4,         -- Limit concurrent compilation jobs
  summary = true,       -- Print summary after completion
})

​
Generating from grammar

Some parsers may need regeneration from source: 
:TSInstallFromGrammar rust
This regenerates parser.c from grammar.json or grammar.js before compiling.
Use this if a parser uses an outdated ABI that’s incompatible with your Neovim version.

​
Updating parsers

Keep parsers synchronized with the plugin: 
:TSUpdate
This updates all installed parsers to match the revisions in the plugin’s manifest. Update specific parsers: 
:TSUpdate rust python
Via Lua: 
-- Update all installed parsers
require('nvim-treesitter').update()

-- Update specific parsers
require('nvim-treesitter').update({ 'rust', 'python' })

-- Update synchronously
require('nvim-treesitter').update():wait(300000)
Always run :TSUpdate after upgrading nvim-treesitter. Parser versions must match the plugin version to ensure compatibility.

​
Managing parsers

​
List installed parsers

Via Lua: 
:lua print(vim.inspect(require('nvim-treesitter').get_installed()))
Via health check: 
:checkhealth nvim-treesitter

​
List available parsers

:lua print(vim.inspect(require('nvim-treesitter').get_available()))
Filter by tier: 
-- 1 = stable, 2 = unstable, 3 = unmaintained, 4 = unsupported
local stable_parsers = require('nvim-treesitter').get_available(1)
print(vim.inspect(stable_parsers))

​
Uninstall parsers

:TSUninstall python javascript
Or in Lua: 
require('nvim-treesitter').uninstall({ 'python', 'javascript' })

​
View installation logs

If installation fails, check the logs: 
:TSLog
This shows all messages from install, update, and uninstall operations.

​
Enabling features

Installing parsers alone doesn’t enable features. You must activate them per filetype.

​
Syntax highlighting

vim.api.nvim_create_autocmd('FileType', {
  pattern = { 'rust', 'javascript', 'python' },
  callback = function()
    vim.treesitter.start()
  end,
})

​
Code folding

vim.api.nvim_create_autocmd('FileType', {
  pattern = { 'rust', 'javascript', 'python' },
  callback = function()
    vim.wo[0][0].foldexpr = 'v:lua.vim.treesitter.foldexpr()'
    vim.wo[0][0].foldmethod = 'expr'
  end,
})

​
Indentation (experimental)

vim.api.nvim_create_autocmd('FileType', {
  pattern = { 'rust', 'javascript', 'python' },
  callback = function()
    vim.bo.indentexpr = "v:lua.require'nvim-treesitter'.indentexpr()"
  end,
})
Note the specific quotes in "v:lua.require'nvim-treesitter'.indentexpr()" - these are required for proper evaluation.

​
All-in-one configuration

vim.api.nvim_create_autocmd('FileType', {
  pattern = { 'rust', 'javascript', 'python', 'lua', 'go' },
  callback = function()
    -- Highlighting
    vim.treesitter.start()
    
    -- Folding
    vim.wo[0][0].foldexpr = 'v:lua.vim.treesitter.foldexpr()'
    vim.wo[0][0].foldmethod = 'expr'
    
    -- Indentation (experimental)
    vim.bo.indentexpr = "v:lua.require'nvim-treesitter'.indentexpr()"
  end,
})

​
Troubleshooting

​
Parser compilation fails

If you see compilation errors:
  1. Verify you have a C compiler: 
    gcc --version  # or clang --version
  2. Check tree-sitter-cli version: 
    tree-sitter --version  # Must be 0.26.1+
  3. Try reinstalling with force: 
    :TSInstall! rust
  4. Try generating from grammar: 
    :TSInstallFromGrammar rust

​
Parser not found

If Neovim can’t find an installed parser:
  1. Check the parser is installed: 
    :checkhealth nvim-treesitter
  2. Verify your installation directory is on the runtimepath: 
    :set runtimepath?
  3. Try reinstalling: 
    :TSUninstall rust
:TSInstall rust

​
Highlighting not working

If syntax highlighting doesn’t activate:
  1. Ensure you’ve called vim.treesitter.start()
  2. Check the language has highlighting queries: 
    :checkhealth nvim-treesitter
  3. Verify the parser loaded correctly: 
    :lua print(vim.treesitter.language.inspect('rust'))

​
Getting help

For issues not covered here:
  1. Run health check: :checkhealth nvim-treesitter
  2. Check installation logs: :TSLog
  3. Search existing issues
  4. Open a new issue with health check output and logs

​
Next steps

Commands reference

Complete list of all available commands and their options

API reference

Lua API documentation for programmatic parser management

Custom parsers

Add parsers not in the default list

Custom queries

Write your own highlighting and folding queries