Skip to main content

Pyrefly in the IDE

Pyrefly seamlessly integrates into IDEs with our VSCode and OpenVSX extensions. For other editors like vim/emacs, see other editors.

Quick start

  1. Install the Pyrefly extension from the VS Code Marketplace or Open VSX.
  2. Open any Python file and the extension will activate automatically.

Supported features

Pyrefly’s language server powers a complete editing experience while fully disabling Pylance, ensuring no interference between checkers.

Each feature below links to the official LSP specification and shows what’s currently supported by Pyrefly.


Go to definition

Jump to where a symbol is declared with a click or F12.


Find references

List all usages of a symbol across your codebase.


Document symbols

See an outline of all top-level items in the current file.


Workspace symbols

Search globally for functions, classes, and variables.


Hover

See type info and docstrings when hovering over code.


Document highlights

Highlights all other instances of the symbol under your cursor.


Signature help

Live function signatures as you type, with parameter hints.


Completion

Autocomplete suggestions for project-specific symbols and imports.


Rename

Safely rename symbols project-wide.


Diagnostics

Type errors and warnings from Pyrefly’s checker appear in the diagnostics pane ("Problems" pane in VSCode).


Semantic tokens

Rich syntax highlighting based on token type and origin.


Inlay hints

Inline hints for types, parameter names, and return values. This is enabled by default; you can disable them using the VSCode Setting.


Notebook support

Works with Jupyter and notebook-style cells.


See planned features and request your own on GitHub.

Customization

By default, Pyrefly should work in the IDE with no configuration necessary. But to ensure your project is set up properly, see configurations.

The following configuration options are IDE-specific and exposed as VSCode settings:

  • Disable language services
    • python.pyrefly.disableLanguageServices [boolean: false]: By default, Pyrefly will provide both type errors and other language features like go-to definition, intellisense, hover, etc. Set disableLanguageServices to true to keep type errors from Pyrefly unchanged but use VSCode's Python extension for everything else.
  • Disable type errors
    • python.pyrefly.disableTypeErrors [boolean: false]: By default, Pyrefly will provide type errors in your project. Set disableTypeErrors to true to prevent type error diagnostics (squiggles) from appearing in the editor.
  • Specify a custom Pyrefly Binary (lspPath)
    • pyrefly.lspPath [string: '']: If your platform is not supported, you can build pyrefly from source and specify the binary path with the lspPath config.
  • Use a specific interpreter
    • If the Python VSCode extension is installed, selecting an interpreter will override the interpreter and settings Pyrefly uses to type check your project, even if one is specified in your Pyrefly configuration.
    • python.defaultInterpreterPath will override the default interpreter selected by VSCode for your workspace.

Issues?

If you experience issues with the Pyrefly extension, please create an issue on github.

Other Editors

Support for other editors is community-driven. If you would like to set this up, please contribute.

Cursor and Windsurf

You can use Pyrefly in your favorite AI Editor that supports OpenVSX extensions. Search for "Pyrefly" in the extension marketplace and install it. Similar to VSCode, Pyrefly will automatically activate when you open a Python file. You will want to disable the other Python language server either by disabling it in the extension settings "Language Server: None" or by disabling the Pyright or BasedPyright extensions.

Jetbrains

An unofficial Jetbrains extension has been developed here

Neovim

Pyrefly supports native Neovim support through lspconfig on Neovim 0.11+. Install and setup Pyrefly using the settings below.

The recommended way to set up Pyrefly in Neovim 0.11+ is:

  1. Install or update the neovim/nvim-lspconfig, mason-org/mason.nvim, and mason-org/mason-lspconfig.nvim plugins with your plugin manager of choice.
  2. Add the following to your Neovim init.lua:
require("mason").setup()
require("mason-lspconfig").setup()
  1. In Neovim, run :MasonInstall pyrefly or add pyrefly to your ensure_installed options:
require("mason-lspconfig").setup {
ensure_installed = { "pyrefly" },
}
Alternative setups and configurations

While the above section describes the fastest way to set up Pyrefly, you may already have a setup or prefer to use other approaches for your lspconfig. Below we describe alternatives to both Pyrefly installation and configuration.

note

We don't provide instructions for setting up Neovim with versions prior to Neovim 0.11, though Pyrefly can work with them through neovim/nvim-lspconfig.

Install Pyrefly for Neovim

There are two methods we currently support for installing Pyrefly for Neovim:

  1. (recommended) Install the mason-org/mason.nvim plugin, which handles installing language services and configuring them easily.
  2. Use a system installation.
mason.nvim

mason.nvim is our recommended approach, since it makes Pyrefly and other language servers, linters, and utilities easily available to Neovim.

note

Installing a binary with Mason will take precedence over other system installations. It might be worth using system installations (including installations in virtual environments) if you need to switch between different versions of Pyrefly for different projects.

Install Mason using your Neovim plugin manager of choice, and make sure you call its setup function to make it available.

To install Pyrefly, run :MasonInstall pyrefly in Neovim, and it will be installed! You can install a specific version of Pyrefly with :MasonInstall pyrefly@<version>, and manage Mason installations (including per-language-server-specific settings!) with :Mason.

System Installations

Pyrefly can also work with Neovim's lspconfig when using a system installation. This will work as long as the Pyrefly binary you want to use is available on your $PATH, which you can check by making sure commands like pyrefly --help succeed. If an installation is available on your $PATH, continue on to configure below.

To install Pyrefly, you can use the package manager of your choice. We support uv, pip, Cargo, and anything else that can interface with PyPI (see Installation for more info).

note

If you're installing Pyrefly into a virtual environment, please be aware that Pyrefly will only work within Neovim if the virtual environment is activated when you start Neovim.

Before moving on, double check that you can access Pyrefly on your $PATH. If you can, then continue with configure.

If Pyrefly is not available on your $PATH, you can try the following:

  • If you're using a virtual environment, try source .venv/bin/activate to ensure your venv is running, then see if pyrefly is available.
  • If you're using uv, you can ensure uv-installed tools are available on your path by running uv tool update-shell.
  • Configure lspconfig to use a specific executable/command by updating your Pyrefly-specific lspconfig settings. To do this, override the cmd configuration option with your command in the configuration section below.
Configure Pyrefly for Neovim

This section describes how to tell Neovim how Pyrefly can be run, as well as how to override those settings.

You have two options on how to do this:

  1. (recommended) Install or update the neovim/nvim-lspconfig plugin to get Pyrefly's (and other language servers') default configs. You can override specific settings if you'd like.
  2. Setup your language server manually without installing extra plugins.
Configs with neovim/nvim-lspconfig plugin

neovim/nvim-lspconfig is a Neovim plugin acting as a repository of language server settings (a repository of language server settings) installed and updated to get Pyrefly's default configuration.

We also recommend installing or updating the mason-org/mason-lspconfig.nvim plugin if you're using Mason, which provides other nice functionality when using Mason with lspconfig. If you install mason-org/mason-lspconfig.nvim, be sure to source it in your Neovim config.

To override specific settings, see :h vim.lsp.config. See :h vim.lsp.Config and :h vim.lsp.ClientConfig for values you can override, and the nvim-lspconfig Pyrefly config for default values.

Example overriding cmd and filetypes

vim.lsp.config('pyrefly', {
-- example of how to run `uv` installed Pyrefly without adding to your path
cmd = { 'uvx', 'pyrefly', 'lsp' }
})
No-plugin Configs

You have the option to setup your language server without neovim/nvim-lspconfig. Simply copy/modify the Pyrefly defaults from nvim-lspconfig in a block like below.

**NOTE: This should be in a file under nvim/lsp/pyrefly.lua

---@type vim.lsp.Config
return {
cmd = { "pyrefly", "lsp" },
}
tip

This Youtube tutorial explains setting up a language server in more depth and with a more organized setup, so check it out if you want to learn more.

Enable Pyrefly for Neovim

If you've installed Pyrefly with Mason and have mason-org/mason-lspconfig.nvim installed, then your language server should just work! You can check by opening a file your language server should cover and running :checkhealth lsp to see if it's started. You may need to restart Neovim for any changes made above to take effect.

Otherwise, to make sure your language servers are activated, be sure to enable them with the syntax below.

vim.lsp.enable({"pyrefly"})
tip

If you're using init.vim, you can use a lua heredoc to execute lua and enable your config.

Vim/Neovim + coc.nvim

Ensure the pyrefly is on $PATH, add following snippet to your coc-settings.json:

"languageserver": {
"pyrefly": {
"command": "pyrefly",
"args": ["lsp"],
"filetypes": ["python"],
"rootPatterns": ["pyrefly.toml", "pyproject.toml", ".git"],
}
},

Vim + ALE

Pull the latest version of ALE and add the following lines to your configuration to enable Pyrefly in Vim with ALE:

let g:ale_linters = {
...
\ 'python': ['pyrefly'],
...
\ }

Emacs

There are several emacs packages that implement the language server protocol; the eglot package is built into recent versions of emacs. You can tell eglot to use pyrefly (which we assume is on your $PATH) with the following configuration:

(add-to-list 'eglot-server-programs
`((python-ts-mode python-mode) . ("pyrefly" "lsp")))

If you are using use-package, this command would run inside of the :config block; a minimal example would look like this:

(use-package eglot
:ensure t
:hook ((python-mode python-ts-mode) . eglot-ensure)
:config
(add-to-list 'eglot-server-programs
`((python-ts-mode python-mode) . ("pyrefly" "lsp"))))

Helix

Ensure that pyrefly is on $PATH (If you got Pyrefly using pip install pyrefly, it should already be on your path). Add this snippet to your languages.toml file

[language-server.pyrefly]
command = "pyrefly"
args = ["lsp"]

[[language]]
name = "python"
language-servers = ["pyrefly"]

Sublime

See the documentation here.