Installation on Linux

It is recommended that you use a Python virtual environment for VPE. The following instructions assume this approach. The virtual environment should be placed within your Vim configuration directory tree, specifically one of:

1. $HOME/.vim/lib/python

2. $HOME/.config/vim/lib/python

Option 1 is currently the more common. Option 2 is only available on platforms that support XDG and is only supported by fairly recent versions of Vim. So use option 1 unless you know better. Option 1 is assumed here.

The following instructions use Python’s built-in venv module. If you prefer another tool, such as uv then you should be able to adapt the procedure.

For the first ever installation

If this is your first VPE installation then you need to:

1. Create the virtual environment.

   # Make sure you are in your $HOME directory
   python -m venv .vim/lib/python
   
   # Activate the virtual environment.
   source .vim/lib/python/bin/activate
   
   # Install VPE.
   python -m pip install vim-vpe
   

2. Without leaving the virtual environment you activated above, start Vim.

3. Within your Vim session enter the commands.

   py3 import vpe
   py3 vpe.post_init()
   Vpe install
   
   " To see what was done
   messages
   

   This installs a file called 000-vpe.vim in you Vim plugin directory and also a help file.

4. Exit the virtual environment.

   deactivate
   

000-vpe.vim

The reason for using the name 000-vpe.vim is to make sure that VPE is fully initialised very early on. This means that other Vim plugins can make use of VPE if desired.

You will only need to activate in the future to upgrade VPE.

For upgrades

1. Activate the virtual environment, upgrade VPE then exit the environment.

   # Make sure you are in your $HOME directory
   source .vim/lib/python/bin/activate
   python -m pip install --upgrade vim-vpe
   deactivate
   

2. Within a new Vim session enter the commands.

   Vpe install
   

   This updates the 000-vpe.vim file and help file.