{"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":"python","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,"search_vec":"'2.1.1':50 '2026':64 'activ':54 'asyncio':70 'cadenc':58 'code':40 'communic':46 'creation':34 'current':47 'custom':28 'develop':55 'editor':69 'enabl':32 'foundat':25 'framework':6 'generic':3,15 'glass':11 'ide':68 'implement':16 'languag':4,19,29,36,65 'like':9 'lsp':67 'maintain':52 'march':63 'minim':39 'pie':10 'pronounc':8 'protocol':21 'pygl':1,7,51 'python':14 'recent':60 'releas':57 'serv':22 'server':5,20,30,37,66,71 'stdio':42 'support':41 'tcp/ip':43 'updat':61 'version':49 'websocket':45 'write':27","created_at":"2026-04-12T03:44:53.286106+00:00","updated_at":"2026-04-17T14:05:59.321847+00:00","problems":[{"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.","cause":"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).","error":"ModuleNotFoundError: No module named 'pygls.lsp'"},{"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`.","cause":"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.","error":"AttributeError: module 'pygls.server' has no attribute 'LanguageServer'"},{"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`.","cause":"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.","error":"cryptic error message on type errors for server commands"},{"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`.","cause":"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.","error":"Unable to deserialize message"},{"fix":"Run 'pip install pygls' to install the library.","cause":"The 'pygls' package has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'pygls'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.1.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/pygls/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}