Configure Pylsp & LSP-Zero In Neovim: A Complete Guide

Oct 16, 2025 by Blender 55 views

Hey guys! So, you're diving into the world of Neovim and want to get your Python development setup just right, yeah? Awesome! This guide is all about configuring pylsp (the Python Language Server) with lsp-zero (a super handy Neovim plugin) and even showing you how to squash those pesky E203 warnings. Let's get started!

Setting the Stage: Why pylsp and lsp-zero?

First off, why these two and not something else? Good question! pylsp is a language server specifically designed for Python. Language servers are like your coding sidekick, providing features like autocompletion, go-to-definition, and error checking, all in real-time. It's built using the Language Server Protocol (LSP), which allows different editors and IDEs to communicate with language servers seamlessly.

Then there's lsp-zero, which is a plugin that makes it super easy to set up and manage LSP servers in Neovim. It simplifies the configuration process, provides sensible defaults, and integrates nicely with other Neovim plugins. Think of it as the friendly wizard that handles all the behind-the-scenes magic, so you can focus on writing code. Using these two together is a powerful combo for Python development in Neovim.

Now, before we get our hands dirty with the configuration, make sure you have Neovim installed and that you know your way around your init.lua or init.vim file (where all your Neovim configurations live). I'm assuming you know the basics of Neovim, like how to install plugins using your favorite plugin manager (like packer.nvim, vim-plug, or lazy.nvim).

To make this as smooth as possible, we will cover all the steps. From installing the necessary tools to customizing your settings and finally, disabling that E203 warning that's been bugging you. Let's make your Neovim setup a Python paradise!

Step 1: Installing the Tools - Mason to the Rescue!

Okay, so the first thing we're going to do is install pylsp using a plugin manager called mason.nvim. Mason is a great plugin that simplifies the installation and management of language servers and other tools. It's like a package manager for all your coding needs.

Install Mason: If you haven't already, install mason.nvim. Here's how it generally looks with packer.nvim:

use {
  "williamboman/mason.nvim",
  config = function()
    require('mason').setup()
  end,
}
use {
  "williamboman/mason-lspconfig.nvim",
  config = function()
    require('mason-lspconfig').setup({
      ensure_installed = {"pylsp"},
    })
  end,
}

Make sure to run :PackerSync (or your plugin manager's equivalent) to install it.

Install pylsp via Mason: Once mason.nvim is installed, open Neovim and run :Mason. This will open the Mason interface. Search for "pylsp" and install it. Mason will handle downloading and setting up pylsp for you.

That's it! Mason takes care of all the heavy lifting, making the installation process super easy. Make sure you don't skip this step, because pylsp is the main tool in our arsenal. It will handle the language server functionality.

Step 2: Configuring lsp-zero for Python Magic

Now that you have pylsp installed, it's time to configure lsp-zero to work with it. The beauty of lsp-zero is that it's designed to be simple and intuitive. Let's dive into the lsp.lua (or wherever you put your lsp-zero config) file and make some magic happen.

Basic lsp-zero Setup: Here's a basic setup in lsp.lua (or similar) to get you started. This usually goes inside a lua/ directory in your Neovim config directory. Adapt the path as needed:
```
local lsp = require('lsp-zero').preset({
  defaults = {
    diagnostics = {
      virtual_text = true,
    },
  },
})

lsp:on_attach(function(client, bufnr)
  -- Your keybindings and other configurations go here (see below)
end)

lsp:setup()
```
This code initializes lsp-zero with some basic settings, including enabling virtual text for diagnostics. This means that errors and warnings will be displayed inline with your code.

Configure pylsp: Next, you need to tell lsp-zero to use pylsp. You can do this by adding pylsp to the servers table in your lsp.lua configuration, like this:

local lsp = require('lsp-zero').preset({
  defaults = {
    diagnostics = {
      virtual_text = true,
    },
  },
  manage_packages = true,
})

lsp:on_attach(function(client, bufnr)
  -- Your keybindings and other configurations go here (see below)
end)

lsp:configure_server( {
  name = 'pylsp',
  settings = {
    pylsp = {
      plugins = {
        pycodestyle = {
          enabled = true,
        },
        pylint = {
          enabled = false,
        },
      },
    },
  },
})

lsp:setup()

The important part is the configure_server call where you specify the server name (pylsp) and potentially some settings. The example includes settings to enable pycodestyle and disable pylint. This example configures pylsp, enabling pycodestyle checks and disabling pylint. Adjust these settings based on your preferences.

Keybindings (Optional, but highly recommended): While lsp-zero provides sensible defaults, adding keybindings makes your workflow much smoother. Here are some keybindings you might find useful. Add these to the on_attach function:

local keymap = vim.keymap
keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = bufnr, desc = 'Show hover' })
keymap.set('n', 'gd', vim.lsp.buf.definition, { buffer = bufnr, desc = 'Go to definition' })
keymap.set('n', 'gi', vim.lsp.buf.implementation, { buffer = bufnr, desc = 'Go to implementation' })
keymap.set('n', 'gr', vim.lsp.buf.references, { buffer = bufnr, desc = 'Find references' })
keymap.set('n', '<leader>d', vim.lsp.buf.diagnostics, { buffer = bufnr, desc = 'Show diagnostics' })
keymap.set('n', '<leader>rn', vim.lsp.buf.rename, { buffer = bufnr, desc = 'Rename' })

These keybindings provide quick access to common LSP features like hovering, going to definitions, finding references, and renaming symbols. The <leader> key is typically set to \ by default, but you can change it in your Neovim configuration if you want.

Save your lsp.lua file and restart Neovim or source the file (:source % in normal mode) to apply the changes. Now, when you open a Python file, lsp-zero should automatically start pylsp, and you should see diagnostics (errors and warnings) in your code.

Step 3: Killing E203 - Disabling Specific Warnings

Alright, time to get rid of that pesky E203 warning. This warning usually relates to whitespace around operators, and while it's good to be consistent, sometimes you might want to ignore it, or you are testing something.

Understanding the Issue: The E203 error is a stylistic issue reported by pycodestyle. To disable it, you need to configure pylsp to ignore this specific error code.

Configuration in lsp.lua: The easiest way to configure it is to modify the settings in your lsp.lua file. Here's how you can disable E203:

local lsp = require('lsp-zero').preset({
  defaults = {
    diagnostics = {
      virtual_text = true,
    },
  },
  manage_packages = true,
})

lsp:on_attach(function(client, bufnr)
  -- Your keybindings and other configurations go here (see below)
end)

lsp:configure_server( {
  name = 'pylsp',
  settings = {
    pylsp = {
      plugins = {
        pycodestyle = {
          enabled = true,
          ignore = {'E203'},
        },
        pylint = {
          enabled = false,
        },
      },
    },
  },
})

lsp:setup()

We add an ignore option to the pycodestyle configuration. It's an array, so you can add more error codes to ignore if needed. Save the lsp.lua file and restart Neovim or source the file (:source %) for the changes to take effect. Open your Python file, and the E203 warning should be gone!

This method is super effective and keeps your configuration organized within the same file. It also ensures that the settings are applied every time you open a new Python file.

Step 4: Troubleshooting and Further Customization

So, you've set up pylsp with lsp-zero, disabled that pesky E203 warning, and hopefully, you're enjoying a smoother coding experience. But what if things aren't working quite right? And how can you take this setup even further?

Troubleshooting Tips

Check the Logs: If pylsp isn't starting or behaving as expected, check Neovim's logs. You can usually access them with :LspLog. This will show you any errors or warnings related to the language server.
Restart Neovim: Sometimes, the simplest solution is to restart Neovim. This ensures that all configurations are reloaded.
Verify pylsp Installation: Double-check that pylsp is installed correctly through Mason. Sometimes, installations can fail.
Ensure Python is in PATH: Make sure that the Python interpreter you want to use is in your system's PATH. pylsp needs to find the Python executable.
Check lsp-zero Version: Ensure you're using a recent version of lsp-zero. Older versions might have bugs or compatibility issues.

Further Customization

Custom Keybindings: Experiment with different keybindings to optimize your workflow. You can bind commands to do things like automatically format your code or run tests.
Formatting: Consider using a code formatter like black or autopep8. Configure pylsp to use these formatters to automatically format your code when you save the file.
Other Plugins: Integrate lsp-zero with other Neovim plugins for even more features. For example, you can use a plugin like nvim-cmp for advanced autocompletion.

Conclusion: Happy Pythoning!

There you have it! A complete guide to setting up pylsp with lsp-zero in Neovim, including how to disable those annoying E203 warnings. This setup should give you a fantastic Python development experience, with features like autocompletion, error checking, and easy navigation through your code.

Remember, the key to a good setup is to keep it simple, test often, and customize it to your liking. Don't be afraid to experiment with different settings and plugins to find what works best for you. Now go forth, code with confidence, and enjoy the power of Neovim and the Language Server Protocol!

If you have any questions or run into any issues, feel free to drop a comment. Happy coding, and have fun with your Neovim setup!