sage-lsp

Description

SageMath Language Server Protocol

Tip

This project may work well with SageMath 10.8+. Other versions lack stubs for Cython files, so they may have limited functionality.

However, until now (2026-2-13), SageMath 10.8 is not accessible from conda-forge (but it released on github). Meanwhile, maintainer doesn't include .pyi files in the build system, so you can't simply install it from pip either.

You may need to install it from source code. And edit some code.

git clone --branch 10.8 --single-branch https://github.com/sagemath/sage.git
cd sage
mamba env create --file environment-3.12-linux.yml --name sage10.8
mamba activate sage10.8

Edit ./tools/update-meson.py like this

@@ -93,3 +93,3 @@
       python_files = sorted(
-            list(folder.glob("*.py")) + list(folder.glob('*.pxd')) + list(folder.glob('*.pyx'))
+            list(folder.glob("*.py")) + list(folder.glob('*.pxd')) + list(folder.glob('*.pyx')) + list(folder.glob('*.pyi'))
       )  # + list(folder.glob('*.pxd')) + list(folder.glob('*.h')))

Run ./tools/update-meson.py to regenerate meson.build files. Then you can install it.

python ./tools/update-meson.py
pip install .

Using sage --version to check if successfully installed.

Warning

If raising error about ImportError: cysignals.signals does not export expected C function _do_raise_exception, using following command to fix it.

pip uninstall cysignals
conda install cysignals

Features

Supported from plugins(very thanks to those projects, they finished a lot of work):

• pygls basic LSP server framework
• pycodestyle linter for style checking
• autopep8 formatter for code formatting
• pyflakes linter for error checking
• jedi definition, type definiton, hover, references provider
• parso(dependency of jedi) for folding
• docstring-to-markdown praser for converting docstrings to markdown for hover information

Supported from native code:

• Support Jupyter notebook
• Only support using from sage.xxx import xxx or import sage.xxx (no alias)
• Local symbols cache for Sage
• Custom formatting rules for Sage
• Custom error checking for Sage
• Custom definition for Sage symbols
• Custom hover information for Sage symbols
• Check references for Sage (only in current file)
• Jump to definiton in Cython files (.pyx) from Stubs (.pyi) in Sage 10.8+
• Support type inference for Sage (depend on .pyi in Sage 10.8+)
• Support type hints hover info for unfollowed variables
• Quick fix for undefined name in Sage
• Completion for Sage (depend on .pyi in Sage 10.8+)

Install

From source code:

git clone https://github.com/SeanDictionary/sage-lsp && cd sage-lsp
pip install .

From pip:

pip install sage-lsp

Usage

Directly run the server

sagelsp --help  // print usage information
sagelsp --sage  // print if SageMath is available and its version
sagelsp -l      // set log level (default: INFO)
sagelsp --clear // clear local symbols cache and exit

Configuration

The server reads style-related configuration from:

1. Global config: ~/.config/pycodestyle
2. Project config in workspace root: .pycodestyle, setup.cfg, tox.ini

Project config overrides global config.

For project config files, only the first file found in this order is used:

1. .pycodestyle
2. setup.cfg
3. tox.ini

The parser currently reads these sections:

• [pycodestyle]
• [autopep8]
• [notebook]

Top 2 sections are

[pycodestyle]

Used for style diagnostics from pycodestyle.

Supported keys:

• select
• ignore
• exclude
• max-line-length
• indent-size
• hang-closing
• experimental
• aggressive

Example:

[pycodestyle]
ignore = E741, E742, E743, E722, E501
max-line-length = 160

[autopep8]

Used for formatting from autopep8.

Supported keys:

• select
• ignore
• exclude
• max-line-length
• indent-size
• hang-closing
• experimental
• aggressive

If [autopep8] is missing, the server falls back to [pycodestyle] for formatter config.

Example:

[autopep8]
max-line-length = 100
aggressive = 1

[notebook]

Used for Jupyter notebook cell-specific overrides.

At the moment, this section supports:

• ignore

Its values are appended to the normal config when formatting or linting notebook cells.This is useful for rules that are often noisy in cells, such as trailing blank lines at the end of a cell.

Example: Usually, checking W391 (blank line at end of file) and W292 (no newline at end of file) is useless in notebook cells

[notebook]
ignore = W391, W292

Complete example

All sections can be empty.

[pycodestyle]
ignore = E741, E742, E743, E722, E501
max-line-length = 160

[autopep8]
max-line-length = 120
aggressive = 1

[notebook]
ignore = W391, W292

Using with extension SageMath-for-VScode

Tip

Make sure you have installed the package sage-lsp in the same Python environment as your SageMath installation, and that the extension can import it.

Install pre-release version 2.0.2-beta from Extension Market to try the new features.

The sorce code of the extension is in SeanDictionary/SageMath-for-VScode. You can also download the pre-release version from GitHub Releases

Change Logs

See CHANGELOG.md

Contributing

See CONTRIBUTING.md

License

This project is licensed under the GPL-3.0 License. See the LICENSE file for details.