rocks.nvim: plugin management that moves the dependency declaration to the author

A rocks.toml, a rockspec, and a registry in between

rocks.nvim is a Neovim plugin manager inspired by Cargo and powered by luarocks, and the whole architecture follows from that pair of comparisons.

The Cargo half is the file format. Plugins are declared in a `rocks.toml` file, which is the manifest a Cargo user would recognise, and the installation is name-based: a plugin published as `nvim-neorg/neorg` is installed with `:Rocks install neorg` rather than with a repository URL. The luarocks half is the machinery underneath, and it is what supplies the features the README lists. Automatic dependency and build script management comes from the rock resolution. True semantic versioning comes from the same place, and the support for multiple versions of the same dependency comes from the luarocks package loader.

The direction of responsibility is the interesting part, and the README states it as the design. Integrating directly with luarocks shifts the responsibility of specifying dependencies and build steps from users to plugin authors. The user declares a plugin, and the plugin's own rockspec declares what it needs, and the tool works out the rest.

The rest of the feature list is smaller than that core: a minimal, non-intrusive UI, async execution, an extensible Lua API, and command completions for plugins and versions on luarocks.org. Binary rocks are pulled from a separate rocks-binaries project, so a rock with a compiled component does not have to be compiled on the machine that installs it.

The project is GPL-3.0 licensed, the primary language is Lua, the default branch is `main`, and the last push was on 2026-10-15. The recent releases are v2.49.1 on 2026-10-15, v2.49.0 on 2026-05-15 and v2.48.0 on 2026-05-03, and the documentation is a plain text file, `doc/rocks.txt`, linked as the help.

The philosophy in the README is the UNIX one, do one thing well. It does not dictate how a user configures plugins, and the configuration module is optional.

The pain the design is aimed at

The README explains the motivation at length, and the reason it gives is worth reading before anyone installs it, because the argument is a criticism of how plugin management usually works.

The traditional approach often places an unjust burden on users, by requiring them to declare dependencies and build instructions manually. The pain points that follow are listed as three.

Breaking changes: updates to a plugin's dependencies or build instructions can lead to breaking changes for users. Platform-specific complexity: both dependencies and build instructions may vary by platform, adding complexity for users. And poor user experience: because of it, plugin authors have been reluctant to add dependencies, preferring to copy and paste Lua code instead, often reinventing the wheel in a suboptimal manner.

That third point is the real one, and it explains the whole design. A plugin that needs a tree-sitter parser, or a specific library version, cannot declare that in a way the plugin manager understands, so the author inlines the code, and the result is a dependency graph nobody can see and a build that has to be redone for every platform. Moving the declaration into the rockspec means the dependency is recorded once, by the person who knows it, in a format the tool can act on.

The README is also careful about the alternatives. Other more modern approaches rely on plugin authors providing this information in their source repositories, and there is a detailed article in the wiki about why a different approach was chosen, with the comparison framed around the packspec, or `pkg.json`, format. So the choice is not between a manifest and a registry in the abstract, it is between two ways of getting a plugin author to declare dependencies, and rocks.nvim is the one that puts the declaration in a rock, where a registry can index it.

The v3 rewrite is the headline, and it is in the README

The first thing the README says, in a warning block, is that rocks.nvim will be undergoing a major rewrite soon, and that if you are considering switching from another plugin manager and would like to avoid churn, the recommendation is to wait for rocks.nvim v3.0.0.

That recommendation is worth taking seriously, because it is a project telling its potential adopters to hold off, and it is rare to see that stated this plainly.

The version numbers tell the rest of the story. The 2.x line is at v2.49.1, published on 2026-10-15, which came five months after v2.49.0 on 2026-05-15, itself twelve days after v2.48.0 on 2026-05-03. A minor version in the 40s, released in a steady trickle, is what a project looks like when it has settled into a mature line, and the rewrite is a deliberate break from it rather than an incremental change.

For a user, the practical question is what a migration would involve. The 2.x line is documented in `doc/rocks.txt`, generated from the source, so the commands are known and the configuration format is documented. What is not known from the repository is what v3 changes, and that is the risk: adopting a plugin manager that is about to be rewritten means a second migration shortly after the first.

There is a mitigation that is visible in the feature list, the support for multiple versions of the same dependency, which comes from the luarocks package loader. A project that needs both the old and the new line of a plugin during a transition can hold two versions at once, which is exactly the situation a rewrite creates for the plugins that depend on it.

Tree-sitter parsers: NURR, prebuilt binaries, per-parser pinning

The tree-sitter story is the most concrete demonstration of the design, because it is the case where the dependency problem is real and the answer has to be a package.

The Neovim User Rocks Repository, NURR, automates the packaging and publishing of many plugins and curated tree-sitter parsers for luarocks. The curation has a limit that the README states plainly: only parsers which can be installed in the NURR CI are uploaded, and that CI is tested on Linux.

For the user, the practical effect is that a parser does not have to be compiled. When installing, rocks.nvim searches the rocks-binaries server, so prebuilt binaries are downloaded, and the parsers come bundled with queries, so enabling syntax highlighting is a call to `vim.treesitter.start()`. The `rocks-treesitter.nvim` module does the same automatically, and the README points out a bonus of the design, that each tree-sitter parser can be pinned and rolled back individually. That is a direct consequence of the rockspec being the unit of dependency: a parser is a rock, so a parser has a version, and a version can be pinned.

For the plugin author, the same mechanism applies in the other direction: specifying a tree-sitter parser as a dependency is as straightforward as including it in the project's rockspec, and the parser is then resolved and installed automatically, with no manual parser management.

There is a warning in this section that says the project is not affiliated with the nvim-treesitter maintainers, and asks that tree-sitter problems not be reported to them. That is a sign of where the boundary of responsibility sits: rocks.nvim packages the parsers, and the syntax highlighting plugin that uses them is somebody else's project.

A Lua API and four companion plugins

The extension story is a Lua API plus a set of separate plugins rather than a single growing binary, and the separation is the design.

`rocks-git.nvim` installs from git repositories, and it is what covers the plugins that are not published on LuaRocks. The README notes that many Neovim plugins and tree-sitter parsers have been packaged for luarocks under the neorocks module, and that an increasing number of plugin authors have been publishing themselves under the neovim label on luarocks.org. So the fallback exists for the long tail, and the direction of travel is that the fallback becomes less necessary.

`rocks-config.nvim` handles plugin configuration, and it is explicitly optional, because the core does not dictate how a user configures plugins.

`rocks-lazy.nvim` adds lazy-loading, and `rocks-treesitter.nvim` handles parser installation and enabling syntax highlighting, the feature described above. The README also points at a topic page for the wider set of rocks-related plugins.

The rest of the feature list is what a modern Neovim plugin has to have to be usable at all: a minimal, non-intrusive UI, so that managing plugins does not take over the editor, and async execution, so that a network operation during installation does not freeze the session. Command completions for plugins and versions, sourced from luarocks.org, are the small touch that makes the install command usable without memorising names, which matters for a tool whose whole point is that you do not need to know the repository URL.

stylua, luacheck, busted and a documentation file generated by vimcats

The repository is a Lua project with a conventional toolchain, and the `Makefile` is short enough to read in one look.

format:
	stylua -v --verify lua/rocks/ plugin/ installer.lua

check:
	luacheck lua/rocks plugin/ installer.lua

test-offline:
	busted --run=offline spec

docgen:
	mkdir -p doc
	vimcats lua/rocks/{init,commands,config/init,meta,api/{init,hooks},log}.lua > doc/rocks.txt

`format` verifies the formatting with stylua rather than rewriting it, which is what a continuous integration job wants, and `stylua.toml` holds the style configuration. `check` runs luacheck, with the configuration in `.luacheckrc`. The test suite is busted, with the configuration in `.busted` and the specs in `spec/`, and the target is named `test-offline` for a reason, since it runs the suite with the `offline` tag, that is without the tests that reach the network.

`docgen` is the one worth looking at. The documentation a user reads, `doc/rocks.txt`, is generated from the source by vimcats, and the file list shows exactly which modules are included: the initialiser, the commands, the configuration, the metadata, the API with its hooks, and the log. The help the user opens in the editor therefore cannot drift from the code, because it is not written by hand.

The rest of the tree is the packaging around that: `installer.lua` and `bootstrap.lua` at the root, the `lua/` and `plugin/` directories, a `rocks.nvim-scm-1.rockspec` describing the plugin itself as a rock, `flake.nix` and `flake.lock` at the root for a Nix development environment, and a `nix/` directory, an `.envrc` for direnv, and the usual `CHANGELOG.md`, `CONTRIBUTING.md` and `LICENSE`.

Where rocks.nvim is the wrong tool

The limits are visible in the design, and a user who does not share the design's premises should not switch.

The first is the toolchain. rocks.nvim is powered by luarocks, and luarocks is a Lua package manager that has to exist on the machine, with a compiler for the rocks that need one, and the documentation assumes you are comfortable with that world. A Neovim user whose configuration is a single Lua file and who has never installed a rock is being asked to learn a package ecosystem to manage plugins, which is a real cost for a benefit that only exists if plugins declare their dependencies properly.

The second is that the value depends on the other side. The whole argument is that plugin authors publish rockspecs so that users do not have to declare dependencies. That works for the plugins that are packaged, and the README is candid that rocks-git.nvim is the fallback for the ones that are not. A user whose plugin set is mostly unmaintained or personal plugins will spend effort on a system whose advantages those plugins cannot use.

The third is the rewrite. The README recommends waiting for v3.0.0 to avoid churn, and that is the recommendation for anyone who is considering a switch. The 2.x line is mature, but the next major version is already announced, so a switch today is a switch into a line that will be replaced.

The alternative is the manifest approach that the README argues against, and it still wins in a few cases. A user who wants lazy-loading, a small footprint and a configuration they can read in one screen is better served by a manifest that lists git repositories and leaves the dependency handling to the plugin author, which is the copy-and-paste pattern that the rocks design was invented to end.

There is a third option, which is to use a manifest for what is installed and luarocks for what is compiled, and that is a hybrid rather than a decision. The difference in approach between the two designs is where the truth about a dependency lives: in the user's file, in which case the user is the source of truth and the manager is a convenience, or in the author's rockspec, in which case the author is the source of truth and the registry is the index. rocks.nvim is a bet on the second, and a user should adopt it only if they think plugin authors will make the effort.

Editorial conclusion

rocks.nvim fits a Neovim user who wants plugin dependencies resolved by a registry instead of by a manifest, and who is willing to install a luarocks toolchain and to accept that a plugin has to be published as a rock before it can be managed this way. It is the wrong choice for a user who wants a lazy-loading setup with a single file, and the wrong choice to start today if you want stability, because the README itself recommends waiting for v3.0.0 to avoid churn. Before switching, read the `rocks.nvim` documentation for the rocks.toml format, check whether the plugins you use are published as rocks at all, since `rocks-git.nvim` is the fallback for the ones that are not, and treat the v2 to v3 migration as a project rather than an upgrade.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. lumen-oss/rocks.nvim on GitHub
4. README
5. Releases