README.md

May 10, 2026 · View on GitHub

JetBrains Marketplace JetBrains Marketplace Downloads GitHub Downloads (all assets, all releases) GitHub commits since latest release

This is a plugin that adds Xonsh language support to JetBrains IDEs (IntelliJ, PyCharm, etc.).

You can install it from your IDE or the Marketplace, or build it from source (see below).

Status: It works. I intend to fix bugs and possibly make improvements over time. Issues and PRs are welcome!

Features

Features are basically that of xonsh-language-server:

  • Syntax highlighting
  • Code completion
  • Inspections / diagnostics
  • Documentation on hover, and other useful info such as env var values.
  • Go To Declaration, Show/Find Usages
  • and more

Install

Prerequisites

IntelliJ-based IDE (PyCharm, etc.) v2024.2+ with LSP4IJ plugin (installed automatically).

xonsh-lsp is run via uvx or pipx unless installed in PATH or specified in Language Server settings. ℹ️ As of 05/2026, xonsh-lsp doesn't work if installed/run with mise (starts but doesn't start its backend).

The plugin is known to work on Linux and macOS. I expect it to work on Windows if xonsh-lsp does as well.

Python LSP backend

xonsh-lsp supports several Python backends:

  • jedi (default, built-in), pyright, and pylsp work well out of the box.
  • basedpyright, ty, and lsp-proxy don't work as well as of 05/2026.

⚠️ Known Issue

If *.xsh / *.xonshrc files are registered as Python in your IDE (which PyCharm may suggest), the plugin will not work on them. To fix it, go to Settings → Editor → File Types → Python and remove xsh extensions, then restart the IDE.

Development

Build from source

Requires JDK 21 (will download on build if you don't have it installed).

./gradlew buildPlugin

The package is created in ./build/distributions/

Sandbox IDE

./gradlew runIde launches a sandbox IDE with the plugin loaded.

By default, it downloads PyCharm from Maven. To skip the download and use your locally installed IDE, create local.properties at the project root:

#localIdePath=/Applications/PyCharm Professional.app/Contents
#localIdePath=/home/<user>/.local/share/JetBrains/Toolbox/apps/intellij-idea-ultimate
localIdePath=/snap/pycharm-community/current

Credits

Most features are provided by xonsh-language-server.

Syntax highlighting outside LSP scope uses the TextMate grammar from vscode-xonsh, itself based on MagicPython.

Logo from the Xonsh project (MIT License).