# How to configure PyCharm for type checking in a uv project


Use [Pyrefly](https://pydevtools.com/handbook/reference/pyrefly.md) from the project's [uv](https://pydevtools.com/handbook/reference/uv.md) environment so PyCharm and CI use the same locked checker. For interpreter and pytest setup, first [configure PyCharm for a uv project](https://pydevtools.com/handbook/how-to/how-to-configure-pycharm-for-a-uv-project.md).

## Prerequisites

- A uv project with a local `.venv` interpreter selected in PyCharm
- A PyCharm installation with **Settings | Python | Type Engine** and the **Types:** status-bar widget

The [external type engine](https://www.jetbrains.com/help/pycharm/python-type-engine.html) supports local interpreters. Docker, WSL, and SSH interpreter configurations use PyCharm's built-in engine.

## Install and configure Pyrefly

```bash
uv add --dev pyrefly
```

The `--dev` flag marks Pyrefly as a {{< term "dev-dependency" "development dependency" >}}, keeping it out of production installs. Commit `uv.lock` so CI and the project environment resolve the same version.

For a project without Pyrefly configuration, add this table to `pyproject.toml`:

```toml {filename="pyproject.toml"}
[tool.pyrefly]
preset = "default"
```

Keep an existing configuration when one is present. Without native configuration, Pyrefly can migrate an existing checker's settings in memory; otherwise it falls back to a basic preset that suppresses some type errors. An explicit preset avoids relying on that fallback.

Run the project's checker:

```bash
uv run pyrefly check
```

`uv run` executes the command inside the project's virtual environment, ensuring all dependencies are installed first. Expect diagnostics for the configured project scope, or a summary reporting zero errors. Resolve CLI errors before diagnosing the editor.

## Select the type engine and its features

Open a Python file, click **Types: Built-in** in the status bar, and select **Pyrefly**. Alternatively, select it under **Settings | Python | Type Engine**.

This delegates type inference and type-related diagnostics to Pyrefly. In Type Engine settings, expand **Other Features** and enable **Inlay hints** and **Documentation** if those should also come from Pyrefly; both options are off by default.

## Check the external-tool integration

Open **Settings | Python | Tools | External Tools** and confirm that Pyrefly is enabled. The type-engine selection and tool configuration are stored separately, so inspect both when diagnostics are missing.

The lookup chain tries **Env** (the project environment), then **Path**, then **uvx**. The selected source appears in bold. With Pyrefly installed in the selected `.venv`, Env should resolve it; a missing Path lookup alone does not establish a failure. Older dialogs may label the environment lookup **Sdk**.

Expand the Pyrefly row to select the features it contributes. Keep one primary checker to avoid duplicate diagnostics. PyCharm also has integrations for [ty](https://pydevtools.com/handbook/reference/ty.md), [Pyright](https://pydevtools.com/handbook/reference/pyright.md), and [Basedpyright](https://pydevtools.com/handbook/reference/basedpyright.md); these external-tool integrations do not replace the built-in type engine.

## Share and verify the setup

PyCharm saves the type-engine choice to `.idea/pyTypeEngine.xml` and tool options to `.idea/pyLspTools.xml`. Commit the files generated by PyCharm together with `pyproject.toml` and `uv.lock`. Keep machine-specific executable paths out of shared settings.

After cloning, run `uv sync --locked`, select the project's interpreter, and open a Python file. Confirm that the **Types:** widget names Pyrefly and that diagnostics agree with `uv run pyrefly check`. Feature toggles and editor filtering can affect what appears, even with the same checker.

## Troubleshoot missing diagnostics

- CLI reports errors but the editor is quiet: check the selected interpreter, the Types widget, and Pyrefly's External Tools toggle. Restart the language server after configuration changes.
- CLI is unexpectedly quiet too: inspect the governing Pyrefly configuration and its preset before assuming the code is error-free.
- Pyrefly is missing from Env: run `uv sync --locked` and confirm that Pyrefly is a selected development dependency in that environment.
- A remote interpreter is selected: use the built-in engine, or run the project's checker separately. The external type-engine restriction is documented by [JetBrains](https://www.jetbrains.com/help/pycharm/python-type-engine.html).

For checker selection, compare the practical differences in [Python type checkers](https://pydevtools.com/handbook/explanation/how-do-mypy-pyright-and-ty-compare.md).
