pygls

library2.1.1pypypi✓ verified 25d ago

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.

http-networking serialization

pip install pygls

package ↗

INSTALL

IMPORT

SIG · PYGLS

pygls

http-networkingpythonv2.1.1

Install

2.1s avg

Import

1524ms

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 1.612s · 22.5MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.1s · import 1.436s · 23MB

21MB installed

● package 21MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

LanguageServer

✓ from pygls.lsp.server import LanguageServer

types

✓ from lsprotocol import types

✗ from pygls.lsp 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

✗ from pygls.lsp.methods import COMPLETION

LSP method constants, like types, are now provided by 'lsprotocol' and often have a 'TEXT_DOCUMENT_' prefix in v1.0+.

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()

Debug

Known issues

breakingPygls 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`.

affects: 1.0.0+

breakingPygls 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.

affects: 1.0.0+

breakingPygls 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.

affects: 2.0.0+

breakingPygls 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.

affects: 2.0.0+

gotchaIn 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.

affects: 2.0.0+

gotchaPygls 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')`).

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pygls.lsp'

This error typically occurs when your `pygls` installation is an older version, or you are trying to import LSP types or methods from a path that has changed in recent `pygls` versions (especially after v1.0, where `lsprotocol` became a separate library).

fix

Upgrade `pygls` to a recent version (e.g., `pip install --upgrade pygls lsprotocol`) and update your imports. For LSP types, import directly from `lsprotocol.types` (e.g., `from lsprotocol import types`), and for server components, `from pygls.server import LanguageServer` or `from pygls.lsp.server import LanguageServer` depending on the `pygls` version.

AttributeError: module 'pygls.server' has no attribute 'LanguageServer'

This error indicates that the `LanguageServer` class is not found at the expected location within the `pygls.server` module, which is a common breaking change introduced with `pygls` v2.0 and later versions.

fix

Ensure you are importing `LanguageServer` from the correct path for `pygls` v2.x. The correct import is typically `from pygls.lsp.server import LanguageServer` (as per `pygls` v2.1.1 documentation). Also, ensure `pygls` is updated to a compatible version: `pip install --upgrade pygls`.

cryptic error message on type errors for server commands

This often manifests as a `cattrs.errors.ClassValidationError` and occurs when the arguments passed to your `pygls` server commands do not match the expected type annotations, or when `cattrs` (used by `pygls` for deserialization) cannot handle complex custom types like `dict[str, Any]` without explicit structuring rules.

fix

Carefully review the type annotations for your server command arguments to ensure they precisely match the expected LSP message structure. For complex types or custom classes, you might need to register custom converters with `cattrs` or simplify the argument types to basic LSP types or primitive Python types that `cattrs` can handle automatically. Ensure `lsprotocol` is also updated: `pip install --upgrade lsprotocol`.

Unable to deserialize message

This error, often accompanied by `pygls.exceptions.JsonRpcInvalidParams`, means `pygls` received a malformed JSON RPC message from the client that it could not parse into the expected LSP type. This frequently happens with incorrect `Position` or `Range` objects where required fields like `line` or `character` might be `None` or of an incorrect type.

fix

Examine the client-side code sending the LSP messages to ensure that all required fields in the LSP objects (e.g., `Position`, `Range`, `TextDocumentIdentifier`) are correctly populated with the expected types and values, especially `line` and `character` as integers. Use detailed logging (`logging.basicConfig(level=logging.DEBUG)`) in your `pygls` server to inspect the incoming raw JSON messages for discrepancies. Upgrade `pygls` and `lsprotocol` to the latest versions to benefit from any parsing improvements: `pip install --upgrade pygls lsprotocol`.

ModuleNotFoundError: No module named 'pygls'

The 'pygls' package has not been installed in the current Python environment.

fix

Run 'pip install pygls' to install the library.

Upgrade

Version history

2.1.1latest on PyPI · released Mar 25, 2026

Audit

Dependencies

lsprotocolrequiredProvides automatically generated Language Server Protocol (LSP) types, essential for defining LSP features.

Agent activity

16 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/pygls/ ↗