pygls: The Generic Language Server Framework

2.1.1 · active · verified Sat Apr 11

pygls (pronounced like 'pie glass') is a pythonic generic implementation of the Language Server Protocol, serving as a foundation for writing custom Language Servers. It enables the creation of language servers with minimal code, supporting STDIO, TCP/IP, and WebSocket communication. Currently at version 2.1.1, pygls maintains an active development and release cadence, with recent updates in March 2026.

Warnings

breaking Pygls v1.0 removed its hand-written LSP type and method definitions. All LSP types and method names must now be imported from `lsprotocol.types`. Previous modules like `pygls.lsp.methods` and `pygls.lsp.types` no longer exist.
Fix: Update all LSP type and method imports to `from lsprotocol import types` and use names like `types.TEXT_DOCUMENT_COMPLETION`.
breaking Pygls v1.0 switched from Pydantic to `attrs` and `cattrs` for serialization and deserialization. Any custom LSP models defined in your server will need to be converted to `attrs`-style classes.
Fix: Refactor custom LSP models to use `attrs` decorators and fields instead of Pydantic models.
breaking Pygls v2.0 removes support for Python 3.8. The minimum required Python version is now 3.9.
Fix: Upgrade your Python environment to 3.9 or higher.
breaking Pygls v2.0 includes a major upgrade to `lsprotocol` (v2025.x), bringing support for LSP v3.18 types and standardized object names. This might affect how certain complex LSP types are referenced.
Fix: Review and update usage of LSP types, especially complex or nested ones, to align with the new standardized names from `lsprotocol` v2025.x.
gotcha In pygls v2.0, server commands registered with `@server.command()` now unpack arguments directly into the command method's parameters, rather than passing a single list argument. Type annotations on command parameters can guide automatic JSON-to-attrs conversion.
Fix: Update command handler signatures to accept arguments as individual parameters (e.g., `def my_command(arg1, arg2):`) instead of a single `*args` or `params` list, and consider adding type annotations.
gotcha Pygls uses Python's built-in `logging` module. Server logs will not be visible by default unless you explicitly configure the logging module before starting your server.
Fix: Add `logging.basicConfig(...)` to your server's startup code (e.g., `logging.basicConfig(level=logging.INFO, filename='pygls.log')`).

Install

pip install pygls Basic Installation
pip install pygls[ws] With WebSocket support

Imports

LanguageServer

from pygls.lsp.server import LanguageServer

types
```
from lsprotocol import types
```
As of v1.0, LSP types are imported from the 'lsprotocol' library, not directly from 'pygls'.
TEXT_DOCUMENT_COMPLETION
```
from lsprotocol.types import TEXT_DOCUMENT_COMPLETION
```
LSP method constants, like types, are now provided by 'lsprotocol' and often have a 'TEXT_DOCUMENT_' prefix in v1.0+.

Quickstart

This quickstart demonstrates a minimal pygls language server that provides 'world' and 'friend' as completion items when the user types 'hello.' in a document. The server communicates via standard I/O (STDIO).

from pygls.lsp.server import LanguageServer
from lsprotocol.types import (
    TEXT_DOCUMENT_COMPLETION, CompletionItem, CompletionList, CompletionParams
)

server = LanguageServer('example-server', 'v0.1')

@server.feature(TEXT_DOCUMENT_COMPLETION)
def completions(params: CompletionParams):
    """Returns completion items."""
    document = server.workspace.get_text_document(params.text_document.uri)
    current_line = document.lines[params.position.line].strip()

    items = []
    if current_line.endswith('hello.'):
        items = [
            CompletionItem(label='world'),
            CompletionItem(label='friend'),
        ]
    return CompletionList(is_incomplete=False, items=items)

if __name__ == '__main__':
    # Starts the language server using standard I/O (stdin/stdout)
    server.start_io()

view raw JSON →