NOTICE:

This repository is currently unmaintained. For the time being (as of August, 2023), it is recommended to use one of the following plugin managers instead:

• lazy.nvim: Most stable and maintained plugin manager for Nvim.
• pckr.nvim: Spiritual successor of packer.nvim. Functional but not as stable as lazy.nvim.

packer.nvim

use-package inspired plugin/package management for Neovim.

Have questions? Start a discussion.

Have a problem or idea? Make an issue or a PR.

Packer is built on native packages. You may wish to read :h packages before continuing

Table of Contents

1. Features
2. Requirements
3. Quickstart
4. Bootstrapping
5. Usage
   1. The startup function
   2. Custom Initialization
   3. Specifying Plugins
   4. Performing plugin management operations
   5. Extending packer
   6. Compiling Lazy-Loaders
   7. User autocommands
   8. Using a floating window
6. Profiling
7. Debugging
8. Compatibility and known issues
9. Contributors

Features

• Declarative plugin specification
• Support for dependencies
• Support for Luarocks dependencies
• Expressive configuration and lazy-loading options
• Automatically compiles efficient lazy-loading code to improve startup time
• Uses native packages
• Extensible
• Written in Lua, configured in Lua
• Post-install/update hooks
• Uses jobs for async installation
• Support for git tags, branches, revisions, submodules
• Support for local plugins

Requirements

• You need to be running Neovim v0.5.0+
• If you are on Windows 10, you need developer mode enabled in order to use local plugins (creating symbolic links requires admin privileges on Windows - credit to @TimUntersberger for this note)

Quickstart

To get started, first clone this repository to somewhere on your packpath, e.g.:

Unix, Linux Installation

git clone --depth 1 https://github.com/wbthomason/packer.nvim\
 ~/.local/share/nvim/site/pack/packer/start/packer.nvim

If you use Arch Linux, there is also an AUR package.

Windows Powershell Installation

git clone https://github.com/wbthomason/packer.nvim "$env:LOCALAPPDATA\nvim-data\site\pack\packer\start\packer.nvim"

Then you can write your plugin specification in Lua, e.g. (in ~/.config/nvim/lua/plugins.lua):

-- This file can be loaded by calling `lua require('plugins')` from your init.vim

-- Only required if you have packer configured as `opt`
vim.cmd [[packadd packer.nvim]]

return require('packer').startup(function(use)
  -- Packer can manage itself
  use 'wbthomason/packer.nvim'

  -- Simple plugins can be specified as strings
  use 'rstacruz/vim-closer'

  -- Lazy loading:
  -- Load on specific commands
  use {'tpope/vim-dispatch', opt = true, cmd = {'Dispatch', 'Make', 'Focus', 'Start'}}

  -- Load on an autocommand event
  use {'andymass/vim-matchup', event = 'VimEnter'}

  -- Load on a combination of conditions: specific filetypes or commands
  -- Also run code after load (see the "config" key)
  use {
    'w0rp/ale',
    ft = {'sh', 'zsh', 'bash', 'c', 'cpp', 'cmake', 'html', 'markdown', 'racket', 'vim', 'tex'},
    cmd = 'ALEEnable',
    config = 'vim.cmd[[ALEEnable]]'
  }

  -- Plugins can have dependencies on other plugins
  use {
    'haorenW1025/completion-nvim',
    opt = true,
    requires = {{'hrsh7th/vim-vsnip', opt = true}, {'hrsh7th/vim-vsnip-integ', opt = true}}
  }

  -- Plugins can also depend on rocks from luarocks.org:
  use {
    'my/supercoolplugin',
    rocks = {'lpeg', {'lua-cjson', version = '2.1.0'}}
  }

  -- You can specify rocks in isolation
  use_rocks 'penlight'
  use_rocks {'lua-resty-http', 'lpeg'}

  -- Local plugins can be included
  use '~/projects/personal/hover.nvim'

  -- Plugins can have post-install/update hooks
  use {'iamcco/markdown-preview.nvim', run = 'cd app && yarn install', cmd = 'MarkdownPreview'}

  -- Post-install/update hook with neovim command
  use { 'nvim-treesitter/nvim-treesitter', run = ':TSUpdate' }

  -- Post-install/update hook with call of vimscript function with argument
  use { 'glacambre/firenvim', run = function() vim.fn['firenvim#install'](0) end }

  -- Use specific branch, dependency and run lua file after load
  use {
    'glepnir/galaxyline.nvim', branch = 'main', config = function() require'statusline' end,
    requires = {'kyazdani42/nvim-web-devicons'}
  }

  -- Use dependency and run lua function after load
  use {
    'lewis6991/gitsigns.nvim', requires = { 'nvim-lua/plenary.nvim' },
    config = function() require('gitsigns').setup() end
  }

  -- You can specify multiple plugins in a single call
  use {'tjdevries/colorbuddy.vim', {'nvim-treesitter/nvim-treesitter', opt = true}}

  -- You can alias plugin names
  use {'dracula/vim', as = 'dracula'}
end)

Note that if you get linter complaints about use being an undefined global, these errors are spurious - packer injects use into the scope of the function passed to startup. If these errors bother you, the easiest fix is to simply specify use as an argument to the function you pass to startup, e.g.

packer.startup(function(use)
...your config...
end)

packer provides the following commands after you've run and configured packer with require('packer').startup(...):

-- You must run this or `PackerSync` whenever you make changes to your plugin configuration
-- Regenerate compiled loader file
:PackerCompile

-- Remove any disabled or unused plugins
:PackerClean

-- Clean, then install missing plugins
:PackerInstall

-- Clean, then update and install plugins
-- supports the `--preview` flag as an optional first argument to preview updates
:PackerUpdate

-- Perform `PackerUpdate` and then `PackerCompile`
-- supports the `--preview` flag as an optional first argument to preview updates
:PackerSync

-- Show list of installed plugins
:PackerStatus

-- Loads opt plugin immediately
:PackerLoad completion-nvim ale

You can configure Neovim to automatically run :PackerCompile whenever plugins.lua is updated with an autocommand:

augroup packer_user_config
  autocmd!
  autocmd BufWritePost plugins.lua source <afile> | PackerCompile
augroup end

This autocommand can be placed in your init.vim, or any other startup file as per your setup. Placing this in plugins.lua could look like this:

vim.cmd([[
  augroup packer_user_config
    autocmd!
    autocmd BufWritePost plugins.lua source <afile> | PackerCompile
  augroup end
]])

Bootstrapping

If you want to automatically install and set up packer.nvim on any machine you clone your configuration to, add the following snippet (which is due to @Iron-E and @khuedoan) somewhere in your config before your first usage of packer:

local ensure_packer = function()
  local fn = vim.fn
  local install_path = fn.stdpath('data')..'/site/pack/packer/start/packer.nvim'
  if fn.empty(fn.glob(install_path)) > 0 then
    fn.system({'git', 'clone', '--depth', '1', 'https://github.com/wbthomason/packer.nvim', install_path})
    vim.cmd [[packadd packer.nvim]]
    return true
  end
  return false
end

local packer_bootstrap = ensure_packer()

return require('packer').startup(function(use)
  use 'wbthomason/packer.nvim'
  -- My plugins here
  -- use 'foo1/bar1.nvim'
  -- use 'foo2/bar2.nvim'

  -- Automatically set up your configuration after cloning packer.nvim
  -- Put this at the end after all plugins
  if packer_bootstrap then
    require('packer').sync()
  end
end)

You can also use the following command (with packer bootstrapped) to have packer setup your configuration (or simply run updates) and close once all operations are completed:

$ nvim --headless -c 'autocmd User PackerComplete quitall' -c 'PackerSync'

Usage

The above snippets give some examples of packer features and use. Examples include:

• My dotfiles:
  • Specification file
  • Loading file
  • Generated lazy-loader file
• An example using the startup method: tjdevries
  • Using this method, you do not require a "loading" file. You can simply lua require('plugins') from your init.vim

The following is a more in-depth explanation of packer's features and use.

The startup function

packer provides packer.startup(spec), which is used in the above examples.

startup is a convenience function for simple setup and can be invoked as follows:

• spec can be a function: packer.startup(function() use 'tjdevries/colorbuddy.vim' end)
• spec can be a table with a function as its first element and config overrides as another element: packer.startup({function() use 'tjdevries/colorbuddy.vim' end, config = { ... }})
• spec can be a table with a table of plugin specif