Of course! Enabling Python support in Vim is a common and powerful way to extend its functionality. Here’s a comprehensive guide covering everything from checking for existing support to building it from scratch.

Summary

1. Check First: Most modern Vim installations (including on macOS and Linux) have Python support enabled by default. You should check this before doing anything else.
2. The Easy Way (Pre-installed Vim): If you have vim or nvim (Neovim) from your system's package manager, it's likely already linked to your system's Python 3. You just need to ensure your Python environment is set up correctly.
3. The Hard Way (From Source): If you're building Vim from source or need to link it to a specific Python version (like one from pyenv), you'll need to compile it with the correct flags.

Step 1: Check if Python Support is Already Enabled

Open Vim or Neovim and run the following command in Normal mode:

:version

Look for the output lines that start with or . A means the feature is included, and a means it's disabled.

You are looking for these lines:

+python           /usr/bin/python (for version 3.x)
+python3          /usr/bin/python3

• If you see +python3, you are all set! Your Vim is compiled with Python 3 support. You can skip to Step 3.
• If you see -python3, your Vim does not have Python 3 support. You'll need to recompile it or install a version that does (see Step 2).
• If you see +python (for Python 2), you have Python 2 support. While this can work, Python 2 is end-of-life. It's highly recommended to get Python 3 support instead.

Step 2: Install or Re-compile Vim with Python 3 Support

This is the most involved step. Choose the method that best fits your situation.

Method A: The Easy Way (Using a Package Manager)

This is the recommended approach for most users.

For Linux (Debian/Ubuntu):

The default vim package on Ubuntu/Debian often doesn't include Python 3 support. The package you want is vim-nox.

# Update your package list
sudo apt update
# Install Vim with Python 3 and other scripting language support
sudo apt install vim-nox

For macOS (using Homebrew):

Homebrew's vim formula is compiled with Python 3 support by default.

# If you have the old vim, uninstall it first
brew uninstall vim
# Install the new vim with python3 support
brew install vim

For Windows:

The official Vim for Windows (vim83.exe from the Vim website) is compiled with Python 3 support. Just download and run the installer. It will automatically add Python to the PATH if it's not already there.

Method B: From Source (Advanced)

This is necessary if you need to link Vim to a specific Python interpreter (e.g., one managed by pyenv).

Install Dependencies

You'll need build tools and Python development headers.

• On Debian/Ubuntu:

  sudo apt update
  sudo apt install build-essential python3-dev

• On macOS (using Homebrew):

  brew install python3
  # The python3 formula already installs the headers

Find Your Python 3 Executable and Path

You need the full path to your Python 3 interpreter and its library path.

# Find the executable path
which python3
# Example output: /usr/bin/python3
# Find the library path (for the -L flag)
python3 -c "import sysconfig; print(sysconfig.get_path('stdlib'))"
# Example output: /usr/lib/python3.10

Download and Compile Vim

Go to the Vim FTP site or use wget to get the latest source tarball. We'll use v9.0 as an example.

# Download the source
wget https://ftp.vim.org/vim/unix/vim-9.0.tar.bz2
tar -xvjf vim-9.0.tar.bz2
cd vim-9.0
# Configure and compile
# Use the paths you found in the previous step.
# Replace /usr/bin/python3 and /usr/lib/python3.10 with your actual paths.
./configure --with-python3-config-dir=$(python3 -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))") \
            --enable-python3interp \
            --with-python3-prefix=$(python3 -c "import sys; print(sys.prefix)")
make
sudo make install

• Explanation of flags:
  • --enable-python3interp: Explicitly enables Python 3 interpreter support.
  • --with-python3-prefix: Tells Vim where to find the Python installation.
  • --with-python3-config-dir: This is a more robust way to find the necessary configuration files for linking. The python3 -c command is a reliable way to get this path.

After make install, you can run vim --version again to confirm +python3 is now present.

Step 3: Verify and Use Python Support in Vim

Now that you have Python support, you need to make sure Vim can find your Python packages.

Verify the Interpreter Path in Vim

In Vim, run:

:python3 print(sys.executable)

This will print the exact path to the Python 3 interpreter that Vim is using. It should match the path from which python3. If it points to a different or non-existent Python, you may have issues with package imports.

Install Python Packages for Vim

To use Python-based plugins or scripts, you need to install their dependencies in the same Python environment that Vim is using.

# Install a popular linter, for example
pip3 install pynvim

Create a Simple Test Script

Create a new file test.py:

def vim_print(msg):
    vim.command(f"echom '{msg}'")

Now, open this file in Vim and run the following commands:

" Execute the Python file
:py3file test.py
" Call the Python function from Vim
:py3 vim_print("Hello from Python!")

You should see Hello from Python! appear at the bottom of your screen. If you do, everything is working perfectly!

Common Pitfalls and Solutions

• Problem: py3file my_script.py gives an error like ImportError: No module named 'pynvim'.

  • Solution: This means the Python environment Vim is using doesn't have the package installed. Install it using pip3 in that specific environment. If you use pyenv, make sure you've run pyenv global <your-version> or pyenv local <your-version> before running pip3 install.

• Problem: vim --version shows +python3, but py3 still gives an error.

  • Solution: This usually means the libpython3.so library is not in Vim's search path. When compiling from source, ensure you ran make install and that your LD_LIBRARY_PATH is set up correctly if you installed Python in a non-standard location.

• Problem: I have multiple Python versions (e.g., system Python and pyenv Python). How do I control which one Vim uses?

  • Solution: The best way is to compile Vim from source (Method B) and explicitly point the configure script to the pyenv Python's prefix and config directory. This ensures a hard link to that specific version. You can also use a pyenv shim by creating a pyenv-vim plugin or by using pyenv global before compiling.