How to configure PyCharm for type checking in a uv project
Use Pyrefly from the project’s uv environment so PyCharm and CI use the same locked checker. For interpreter and pytest setup, first configure PyCharm for a uv project.
Prerequisites
- A uv project with a local
.venvinterpreter selected in PyCharm - A PyCharm installation with Settings | Python | Type Engine and the Types: status-bar widget
The external type engine supports local interpreters. Docker, WSL, and SSH interpreter configurations use PyCharm’s built-in engine.
Install and configure Pyrefly
uv add --dev pyreflyThe --dev flag marks Pyrefly as a development dependencyA package needed during development (testing, linting, formatting) that is not shipped to users of your project. Installed with the --dev flag.
, 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:
[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:
uv run pyrefly checkuv 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, Pyright, and Basedpyright; 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 --lockedand 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.
For checker selection, compare the practical differences in Python type checkers.