DEV Community

Luis Noriega
Luis Noriega

Posted on

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

#ai #python #tooling #tutorial

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
  }
}
Enter fullscreen mode Exit fullscreen mode

Or you run:

/plugin install pyright-lsp@claude-plugins-official
Enter fullscreen mode Exit fullscreen mode

And you get:

Plugin "pyright-lsp" not found in any marketplace
Enter fullscreen mode Exit fullscreen mode

Or, after fixing that, you run into:

ENOENT: no such file or directory, uv_spawn 'pyright-langserver'
Enter fullscreen mode Exit fullscreen mode

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
  }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Complete Step-by-Step Fix (5 minutes)

1. Install pyright via pip 

pip install pyright
Enter fullscreen mode Exit fullscreen mode

Verify the executable was created:

where pyright-langserver
Enter fullscreen mode Exit fullscreen mode

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')
Enter fullscreen mode Exit fullscreen mode

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
  }
}
Enter fullscreen mode Exit fullscreen mode

4. Install the plugin and restart 

/plugin install pyright-lsp@claude-plugins-official
Enter fullscreen mode Exit fullscreen mode

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!

Top comments (0)