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 VSCode marketplace or OpenVSX
  2. Open a python file and the extension will activate

Features​

The Pyrefly extension provides:

  • Inline type errors matching the Pyrefly command-line
  • Types shown inline and on hover
  • Go-to definition
  • Autocomplete / intellisense
  • Basic document symbols / breadcrumbs
  • Find references

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:

  • python.pyrefly.disableLanguageServices [boolean: false]: by default, Pyrefly will provide both type errors and other language features like go-to definition, intellisense, hover, etc. Enable this option to keep type errors from Pyrefly unchanged but use VSCode's Python extension for everything else.
  • python.pyrefly.disableTypeErrors [boolean: false]: by default, Pyrefly will provide type errors in your project. Enable this setting to disable type error squiggles appearing in the editor.
  • pyrefly.lspPath [string: '']: if your platform is not supported, you can build pyrefly from source and specify the binary here.

If the project configuration does not specify the Python interpreter, Pyrefly will use the interpreter selected in VSCode.

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.

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 available to Neovim, and makes configuring them easy.

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 between 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 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 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
note

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.

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"]