nvim-treesitter on the main branch: a rewrite that expects Neovim 0.12 nightly

What nvim-treesitter actually provides, and who it is for

The plugin does three things, per its README: it provides functions for installing, updating and removing tree-sitter parsers; it ships a collection of queries that enable tree-sitter features built into Neovim; and it acts as a staging ground for treesitter-based features considered for upstreaming to Neovim. That framing matters because it tells you where the plugin sits. Highlighting and folding are Neovim features now, not plugin features. nvim-treesitter supplies the parsers and the query files those features read.

The audience is Neovim users who want syntax-aware highlighting, folding, indentation and multi-language injection handling in files Neovim's own runtime does not cover well. It is not a general-purpose parsing library and it is not a standalone tool. Everything it installs is consumed by Neovim at runtime through runtimepath. If you do not use Neovim, nothing here applies to you.

The main branch is a different plugin from the one most configs assume

The README opens with a caution: this is a full, incompatible rewrite, and you should treat it as a different plugin you need to set up from scratch. That is the single most important fact on the page. Users upgrading from an older configuration will find that their setup code does not carry over.

The escape hatch is named explicitly. If you cannot or do not want to update, you specify the master branch, which the README describes as locked but kept available for backward compatibility with Nvim 0.11. So the project is maintaining two configurations at once: a frozen one for the previous Neovim line and a rewritten one for the next. Which one you want depends entirely on your Neovim version, and the requirements section settles that question: Neovim 0.12.0 or later, marked as nightly.

The support policy is narrow by design. The README states that only the latest stable release and the latest nightly prerelease are supported, and that other versions may work but are neither tested nor considered for fixes. That is a clear boundary, not a bug.

How parsers and queries get installed and loaded

The mechanism is a directory you control. The setup function takes an install_dir key, described as the directory to install parsers and queries to, which is prepended to runtimepath so it takes priority over anything else. The default shown in the README is vim.fn.stdpath('data') .. '/site'. Parsers and queries land there, and Neovim picks them up as ordinary runtime files.

The install call is asynchronous. The README notes that require('nvim-treesitter').install { 'rust', 'javascript', 'zig' } is a no-op if the parsers are already installed, and that for synchronous installation in a script context you need to wait on the returned object with a millisecond timeout.

Queries are the second half of the pair. The README is explicit that supporting a feature for a language requires both a parser and an appropriate language-specific query file for that feature. A parser without queries gives you a syntax tree and nothing that reads it. That two-part requirement is why the supported-languages page matters more than it looks: it tells you whether both halves exist for the language you care about.

Features are not switched on for you. The README says so directly: these are not automatically enabled. Highlighting, folds and indentation each need their own opt-in, shown in the next section. Locals queries are described as not used in this plugin and provided for limited backward compatibility, which is worth knowing before you build anything on top of them.

Installing nvim-treesitter and enabling highlighting for one filetype

Start with the requirements. The README lists Neovim 0.12.0 or later, tar and curl on your path, tree-sitter-cli 0.26.1 or later installed through your package manager and explicitly not through npm, and a C compiler on your path.

Install the plugin with your package manager of choice. The README's example uses lazy.nvim and sets lazy = false, because the plugin does not support lazy-loading:

{
  'nvim-treesitter/nvim-treesitter',
  lazy = false,
  build = ':TSUpdate'
}

The build key runs :TSUpdate on every plugin update. The README is emphatic about why: the plugin is only guaranteed to work with specific parser versions, as specified in the parser.lua table, and when you upgrade the plugin you must make sure all installed parsers are updated to the latest version. Automating that is strongly recommended.

Calling setup is optional. The README states you do not need to call setup for the plugin to work with default values. If you do call it, this is the shape:

require('nvim-treesitter').setup {
  install_dir = vim.fn.stdpath('data') .. '/site'
}

Then install the parsers you want. This runs asynchronously:

require('nvim-treesitter').install { 'rust', 'javascript', 'zig' }

For a script or bootstrap context, wait on the result with a timeout in milliseconds:

require('nvim-treesitter').install({ 'rust', 'javascript', 'zig' }):wait(300000)

Finally, enable highlighting for a filetype. The README offers an autocmd form:

vim.api.nvim_create_autocmd('FileType', {
  pattern = { '<filetype>' },
  callback = function() vim.treesitter.start() end,
})

After restarting Neovim and opening a file of that type, highlighting should come from the treesitter parser rather than the regex syntax file. If it does not, the parser or the query file for that language is the first thing to check.

Folds, indentation and the experimental label

Folds are a Neovim feature, and the README gives the two window options to set in a ftplugin or FileType autocommand:

vim.wo[0][0].foldexpr = 'v:lua.vim.treesitter.foldexpr()'
vim.wo[0][0].foldmethod = 'expr'

Indentation is different. The README calls treesitter-based indentation provided by this plugin but considered experimental, and the snippet carries a warning about its quotes:

vim.bo.indentexpr = "v:lua.require'nvim-treesitter'.indentexpr()"

That parenthetical about the specific quotes is not decoration. It is the kind of note that exists because the expression is parsed by Vim's expression evaluator, where quoting style changes what resolves. Read it as a signal that this path is less settled than highlighting. If you enable it and indentation misbehaves, the experimental label in the README is the honest starting point, not a bug report.

Injections need no setup at all. They handle multi-language documents, and the README points to :h treesitter-language-injections for the details. For anyone editing files with embedded languages, this is the feature that works without configuration.

Adding a parser the supported list does not cover

The supported-languages page is not exhaustive of what you can run. The README documents adding a parser manually inside a User TSUpdate autocommand, with an install_info table containing a url and a revision commit hash, plus optional branch, location, generate, generate_from_json and queries entries. The queries entry installs queries from a given directory.

A local checkout is also supported through a path key. The README notes that this always uses the state of the directory as-is, meaning branch and revision are ignored. That is a real difference in behavior between the two forms, and it means a local checkout can drift from the revision you thought you pinned.

If the parser name differs from Neovim's filetype, you register it with vim.treesitter.language.register, and the README points to vim.filetype.add() for custom detection when Neovim does not recognize the filetype at all. This is a manual, multi-step path. It is documented, but it is not a one-liner, and the generate and generate_from_json flags exist because some grammar repositories do not ship a pre-generated src/parser.c.

Where nvim-treesitter is the wrong tool

The clearest wrong-tool case is a Neovim older than 0.12.0. The main branch will not serve you; the README directs you to the master branch instead. Installing the main branch on 0.11 and filing issues will get you nowhere, because the support policy covers only the latest stable and latest nightly releases.

The second case is anyone who wants lazy-loading. The README states plainly that the plugin does not support lazy-loading, and the example spec sets lazy = false. If your configuration philosophy depends on deferring plugin startup until a filetype is touched, this plugin does not fit that model.

The third is version drift. Because installed parsers are tied to the parser.lua table, an upgrade that is not followed by :TSUpdate can leave you with parsers the plugin no longer expects. The README does not document a rollback for that situation; it documents the automation that prevents it.

One more boundary: the plugin is not the source of highlighting or folding behavior. Those are Neovim features. If highlighting looks wrong, the parser or the query file is the suspect, not the plugin's rendering code, because there is no rendering code to suspect.

Alternatives and what actually differs

The realistic alternative is not another plugin. It is Neovim's own treesitter support plus parsers you install yourself. Neovim ships the highlighting and folding machinery, and the README says as much when it points to :h treesitter-highlight and describes folds as provided by Neovim. What nvim-treesitter adds is the install, update and removal functions for parsers, the query collection, and the staging ground for features headed upstream.

So the difference in approach is packaging and curation versus doing it by hand. If you manage parsers yourself, you control exactly which revision of which grammar is on disk, and you take on the update discipline that :TSUpdate currently automates. If you use nvim-treesitter, you get a supported list, a single install call, and queries maintained alongside the parsers, at the cost of the plugin's version constraints and its parser.lua coupling.

For the master branch, the alternative is simply staying there. The README frames it as locked but available for backward compatibility with Nvim 0.11, which makes it a deliberate holding position rather than a dead end.

Maintenance, licence and what an upgrade costs

The repository is not archived, and the last push was on 2026-09-19, two days before this writing. On that evidence the project is being worked on right now. There is no tagged release to pin to in what the README and repository layout describe; the branch is the unit of adoption.

The upgrade cost is the part worth budgeting. Every plugin upgrade must be paired with :TSUpdate so installed parsers match the parser.lua table. The README's lazy.nvim example encodes this as build = ':TSUpdate', and calls automating it strongly recommended. If you manage plugins without a build hook, this becomes a manual step you will forget.

The rewrite itself is a migration cost, not a recurring one, but it is paid up front: existing setup code does not carry over, and the README tells you to set the plugin up from scratch.

On licensing, the repository is Apache-2.0. Parsers are separate projects with their own licences, and the plugin installs them from their own repositories, so the licence of a given grammar is not determined by this plugin's licence. That is a question for whoever reviews dependencies in your environment, not something this article can settle.

Editorial conclusion

Adopt the main branch only if you already run Neovim 0.12.0 or later and accept that every plugin upgrade must be paired with :TSUpdate, since the README ties installed parsers to the parser.lua table. If you are on Neovim 0.11, use the master branch instead; it is locked but kept for backward compatibility. Before switching, verify that tree-sitter-cli 0.26.1 or later is installed through your package manager rather than npm, and that tar, curl and a C compiler are all on your path.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. nvim-treesitter/nvim-treesitter on GitHub
4. README