How to Fix pyright-lsp on Claude Code for Windows (The Complete Guide)

Luis Noriega — Mon, 09 Mar 2026 01:33:47 +0000

If you've tried to enable the pyright LSP plugin in Claude Code on Windows and hit a wall, this post is for you. After several hours of debugging, I discovered three separate bugs that compound on Windows. Here's the complete, tested fix.

The Problem

You add this to ~/.claude/settings.json:

{
  "enabledPlugins": {
    "pyright-lsp@claude-plugins-official": true
  }
}

Or you run:

/plugin install pyright-lsp@claude-plugins-official

And you get:

Plugin "pyright-lsp" not found in any marketplace

Or, after fixing that, you run into:

ENOENT: no such file or directory, uv_spawn 'pyright-langserver'

Here's exactly what's happening and how to fix all of it.

Bug #1: Marketplace Not Pre-Registered on Windows

On macOS the official marketplace comes pre-registered. On Windows it doesn't. Claude Code simply doesn't know where to look for the plugin.

Fix: Add extraKnownMarketplaces to ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "claude-plugins-official": {
      "source": {
        "source": "github",
        "repo": "anthropics/claude-plugins-official"
      }
    }
  },
  "enabledPlugins": {
    "pyright-lsp@claude-plugins-official": true
  }
}

Now /plugin install pyright-lsp@claude-plugins-official works.

Bug #2: lspServers Config Not Propagated (Known Issue)

After installing the plugin, the cache folder at:

~/.claude/plugins/cache/claude-plugins-official/pyright-lsp/1.0.0/

only contains LICENSE and README.md. The lspServers config from marketplace.json is never written. This is a known bug (#15148).

Bug #3: libuv Cannot Spawn .cmd Files (The Real Blocker)

npm install -g pyright creates pyright-langserver.cmd (a batch wrapper).

Claude Code uses Node.js internally, which uses libuv (uv_spawn). On Windows, libuv calls CreateProcess directly and does not resolve .cmd extensions.

So uv_spawn('pyright-langserver') will never find the file.

Fix: Install pyright with pip instead of npm (this creates a real .exe):

pip install pyright

Complete Step-by-Step Fix (5 minutes)

1. Install pyright via pip

pip install pyright

Verify the executable was created:

where pyright-langserver

2. Add Python Scripts to the System PATH (Critical!)

Open PowerShell as Administrator:

$scripts = 'C:\Users\<YOUR_USERNAME>\AppData\Local\Programs\Python\Python311\Scripts'
$current = [System.Environment]::GetEnvironmentVariable('PATH', 'Machine')
[System.Environment]::SetEnvironmentVariable('PATH', $current + ';' + $scripts, 'Machine')

3. Register the marketplace and enable the plugin

Edit ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "claude-plugins-official": {
      "source": {
        "source": "github",
        "repo": "anthropics/claude-plugins-official"
      }
    }
  },
  "enabledPlugins": {
    "pyright-lsp@claude-plugins-official": true
  }
}

4. Install the plugin and restart

/plugin install pyright-lsp@claude-plugins-official

Close Claude Code completely and reopen it. Do not use /reload-plugins after restarting.

5. Verify

Open any Python file. You should now see pyright diagnostics appear automatically and be able to use goToDefinition, findReferences, etc.

Why This Matters

With LSP enabled, Claude Code navigates your codebase semantically instead of using plain text search. It understands types, call hierarchies, and cross-file references without reading entire files. For large projects, the difference is massive.

Reported to Anthropic

These bugs are documented in the official issue:

anthropics/claude-code#32268

Hopefully a future version will ship the official marketplace pre-registered on Windows and a proper .exe for pyright-langserver.

Tested on: Windows 11 Pro + Claude Code 2.1.71 (native install) + Python 3.11

Did it work for you? Drop a comment and let me know where you were stuck — happy to help more people!

DEV Community: Luis Noriega