{"id":4192,"library":"pygls","title":"pygls: The Generic Language Server Framework","description":"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.","status":"active","version":"2.1.1","language":"en","source_language":"en","source_url":"https://github.com/openlawlibrary/pygls","tags":["language server","LSP","IDE","editor","asyncio","server"],"install":[{"cmd":"pip install pygls","lang":"bash","label":"Basic Installation"},{"cmd":"pip install pygls[ws]","lang":"bash","label":"With WebSocket support"}],"dependencies":[{"reason":"Provides automatically generated Language Server Protocol (LSP) types, essential for defining LSP features.","package":"lsprotocol","optional":false}],"imports":[{"symbol":"LanguageServer","correct":"from pygls.lsp.server import LanguageServer"},{"note":"As of v1.0, LSP types are imported from the 'lsprotocol' library, not directly from 'pygls'.","wrong":"from pygls.lsp import types","symbol":"types","correct":"from lsprotocol import types"},{"note":"LSP method constants, like types, are now provided by 'lsprotocol' and often have a 'TEXT_DOCUMENT_' prefix in v1.0+.","wrong":"from pygls.lsp.methods import COMPLETION","symbol":"TEXT_DOCUMENT_COMPLETION","correct":"from lsprotocol.types import TEXT_DOCUMENT_COMPLETION"}],"quickstart":{"code":"from pygls.lsp.server import LanguageServer\nfrom lsprotocol.types import (\n    TEXT_DOCUMENT_COMPLETION, CompletionItem, CompletionList, CompletionParams\n)\n\nserver = LanguageServer('example-server', 'v0.1')\n\n@server.feature(TEXT_DOCUMENT_COMPLETION)\ndef completions(params: CompletionParams):\n    \"\"\"Returns completion items.\"\"\"\n    document = server.workspace.get_text_document(params.text_document.uri)\n    current_line = document.lines[params.position.line].strip()\n\n    items = []\n    if current_line.endswith('hello.'):\n        items = [\n            CompletionItem(label='world'),\n            CompletionItem(label='friend'),\n        ]\n    return CompletionList(is_incomplete=False, items=items)\n\nif __name__ == '__main__':\n    # Starts the language server using standard I/O (stdin/stdout)\n    server.start_io()","lang":"python","description":"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)."},"warnings":[{"fix":"Update all LSP type and method imports to `from lsprotocol import types` and use names like `types.TEXT_DOCUMENT_COMPLETION`.","message":"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.","severity":"breaking","affected_versions":"1.0.0+"},{"fix":"Refactor custom LSP models to use `attrs` decorators and fields instead of Pydantic models.","message":"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.","severity":"breaking","affected_versions":"1.0.0+"},{"fix":"Upgrade your Python environment to 3.9 or higher.","message":"Pygls v2.0 removes support for Python 3.8. The minimum required Python version is now 3.9.","severity":"breaking","affected_versions":"2.0.0+"},{"fix":"Review and update usage of LSP types, especially complex or nested ones, to align with the new standardized names from `lsprotocol` v2025.x.","message":"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.","severity":"breaking","affected_versions":"2.0.0+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"2.0.0+"},{"fix":"Add `logging.basicConfig(...)` to your server's startup code (e.g., `logging.basicConfig(level=logging.INFO, filename='pygls.log')`).","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}