Vim Builtin Package Manager

Image of Author
March 14, 2022 (last updated October 24, 2022)

As of vim v8 there is a builtin package manager in vim. It's recommended or in use by popular members of the vim community, including Tim Pope, the creator of pathogen, and romainl who mentioned they use it in a Reddit reply. Tim Pope writes in the opening section of pathogen:

For new users, I recommend using Vim's built-in package management instead. :help packages

The builtin package manager looks for packages inside a ~/.vim/pack/ folder, and loads plugins within them in accordance with certain rules. This makes vim itself a replacement for plugin managers, while at the same time, removing the awkward problems around bootstrapping plugin managers.

You can also store your vimrc file in ~/.vim/. This means all your vim management code can be version controlled independent of the rest of your machine setup. Inside your "dotvim" repo, you can leverage git submodules to version control the packages/plugins you depend on. Theoretically, the end result is a simpler vimrc file. (See Git Submodules to learn more about how they work.)

To me, the most exciting part of all this is that, once you add your plugins to the appropriate folder, everything "just works".

Understanding Packages and Plugins

Packages live in ~/.vim/pack/. Packages are directories with any name, pack/*/. Packages contain plugins in specific locations, the most notable of which is the start directory, pack/*/start/. Plugins also have a particular folder structure. A plugin is a directory with any name, inside of which is, most likely, a plugin directory containing one or more vimscript files, */plugin/*.vim. For plugins in a package start directory, the vimscript files in the plugin's /plugin folder are ran on start of vim, pack/*/start/*/plugin/*.vim.

How to manage plugins without packages

A lot of the vim ecosystem is individual plugins. If you look at the management tools currently popular in the vim ecosystem, you will notice that they all refer to themselves as plugin managers, not package managers. So, the question of package management is a bit of an open issue, as far as I can tell.

About the only thing I'm certain of at this point is that plugins have to live inside packages. So if you want to use individual plugins, you have to figure out what package you will put them in. (Remember, package names are arbitrary, so technically every answer is right. What I'm about to explore is what semantically is right.) A couple options present themselves.

  1. Wrap plugins in packages of the same name. Using vim-sensible as an example, you would store it in pack/sensible/start/sensible/.

  2. Wrap plugins in packages named after their creators. For example, pack/tpope/start/sensible/.

  3. Put plugins in generic packages. For example, pack/plugins/start/sensible/, or pack/bundle/start/sensible.

  4. Create your own personal package. For example, pack/[your-name]/start/sensible/. (You could then version control just this package, and even have it as a submodule of your dotvim files, if you are particularly git happy.)

I've seen blog posts advocate option (3). It seems that Tim Pope might advocate for option (2) based on his setup guides for his own plugins (though it could also be (4)). The docs at :help package-create seem to advocate for option (1), at least on some interpretations. I have no strong preference at the moment.

How I'm managing my vim setup

I am version controlling just my ~/.vim/ folder at aegatlin/dotvim. I like this approach because I can manage vim independently of everything else on my machine. (I have a MacOS Machine Setup guide for interested parties). My package management strategy as per above will be arbitrary. By the time you read my dotvim files, I will likely have succumbed to scope-creep, but my goal is to keep it as simple as possible. (As of this writing, vim is not my primary IDE, so "simple" is arguably an actually achievable goal.)