How we chose Positron’s Python type checker

Python

We tested four open-source Python type checkers to find the best default for Positron. Here’s how Pyrefly, ty, Basedpyright, and Zuban compare on features, correctness, performance, and development velocity.

Author

Austin Dickey

Published

March 27, 2026

The open-source Python type checker and language server ecosystem has exploded. Over the past year or two, four language servers have appeared, each with a different take on what Python type checking should look like. We evaluated each of them to decide which one to bundle with Positron to enhance the Python data science experience.

With AI tools writing more of your code, a good language server helps you read and navigate code you didn’t write. LLM-generated code also introduces bugs that type checkers catch before you run anything. For data scientists, who rely on code to be the reproducibility layer, and who can’t automate away human judgment, what matters is a tool that helps you understand and trust your code.

Tip

Positron’s built-in language server uses your running Python session to provide runtime-aware completions and hover previews. Beyond what’s in code, it knows your DataFrame column names, your dictionary keys, your environment variables, and more. But the tools evaluated in this post handle the static analysis side: type checking, go-to-definition, rename, and code actions. Both run concurrently, and Positron merges their results.

The contenders

Tool	Backing	Language	License	Stars¹
Pyrefly	Meta	Rust	MIT	5.5K
ty	Astral (OpenAI)	Rust	MIT	17.8K
Basedpyright	Community	TypeScript	MIT	3.2K
Zuban	Indie	Rust	AGPL-3.0	1K

Pyrefly is Meta’s successor to Pyre. It takes a fast, aggressive approach to type inference, being able to catch issues even in code with no type annotations. It reached beta status in November 2025.

ty is from Astral, the team behind uv and ruff. OpenAI announced its acquisition of Astral recently; Astral has stated that ty, ruff, and uv will remain open source and MIT-licensed. It’s the newest project, with a focus on speed and tight integration with the Astral toolchain. It reached beta status in December 2025 and follows a “gradual guarantee” philosophy (more on that below).

Basedpyright is a community fork of Microsoft’s Pyright type checker, with additional type-checking rules and Pylance features baked in to enable language server features in your IDE. It’s the most mature of the four and has the largest contributor base.

Zuban is from David Halter, the author of Jedi (the longtime Python autocompletion library). It aims for mypy compatibility and ships as a pip-installable tool.

What we tested

We tested each language server across several dimensions, roughly following the rubric we outlined publicly:

Feature completeness: Completions, hover, go-to-definition, rename, code actions, diagnostics, inlay hints, call hierarchy
Correctness: How well does the type checker handle real-world Python code?
Performance: Startup time and time to first completion
Ecosystem: License, community health, development velocity, production readiness

We tested inside Positron with a mix of data science and general Python code.

Feature completeness

All four provide the core features you’d expect: completions, hover documentation, go-to-definition, semantic highlighting, and diagnostics. The differences show up in the details.

Pyrefly

Strong feature set. The hover documentation is the best of the four; Pyrefly renders it cleanly and sometimes includes hyperlinks to class definitions.

ty

Fast and clean, now in beta. The completion details can sometimes feel a little overwhelming, but can help when expanded.

Basedpyright

Handles type checking comprehensively well. The main friction point: it surfaces a lot of warnings out of the box. If you’re doing exploratory data science, a wall of type errors on your first pandas import can feel hostile. You can tune this down, but the defaults are oriented toward stricter use cases like package development.

Zuban

The least mature of the four so far. Installation requires a two-step process (pip install zuban, then configure the interpreter), and the analysis is tied to that specific Python installation on saved files only. Third-party library completions only work when stubs are available, not from installed packages. Symbol renaming once broke standard library code in our testing.

Tip

Regardless of which tool you choose, Positron’s built-in runtime LSP adds DataFrame column completions (in subscript access, double-bracket selection, and method calls like groupby and sort_values), environment variable completions, namespace-aware completions with live type info, and hover previews showing actual data. These features come from your running Python session, not static analysis, so they work the same with any extension.

Type checking philosophy

The bigger difference between these tools isn’t features but how they think about type checking.

Gradual guarantee vs. aggressive inference

ty follows what’s called the gradual guarantee: removing a type annotation from correct code should never introduce a type error. The idea is that type checking should be additive. You opt in by adding types, and the checker only flags things it’s sure about.

The other extensions take the opposite approach. They always infer types from your code, even when you haven’t written any annotations. This means they can catch bugs in completely untyped code, but it also means they may flag code that runs perfectly fine.

For example:

my_list = [1, 2, 3]
my_list.append("foo")

# Pyrefly: bad-argument-type
# ty: <no error>
# Basedpyright: reportArgumentType
# Zuban: arg-type

Pyrefly infers my_list as list[int] and flags the append("foo") call as a type error. ty sees no annotations and stays silent. The code is dynamically typed and that’s fine.

If you’re doing exploratory data analysis and don’t want to annotate everything, ty’s restraint is more comfortable. But if you’re writing a library and want to catch bugs early, Pyrefly’s aggressiveness is helpful. For example:

def process(data):
    return str(data)

process(42) + 1  # Raises a runtime AttributeError

# Pyrefly: unsupported-operation
# ty: <no error>
# Basedpyright: reportOperatorIssue
# Zuban: operator

Basedpyright and Zuban land somewhere in between, with Basedpyright leaning toward stricter checking and Zuban aiming for mypy compatibility.

For a deeper dive on this topic, Edward Li’s comparison of Pyrefly and ty and Rob Hand’s overview of future Python type checkers are both worth reading, though some bugs have been fixed since they were published.

Performance

We measured startup time (how long until the language server responds to an initialize request) and time to first completion (how long a textDocument/completion request takes after initialization) in a relatively small repository. We ran each measurement five times and averaged. As always, these results only represent our computer’s experimental setup.

LSP	Avg. startup (s)	Avg. first completion (ms)
Pyrefly	5.8	190
ty	2.2	88
Basedpyright	3.1	112
Zuban	N/A²	97

ty was the fastest across the board (no surprise from Astral). But the practical differences are small: a 3-second difference in startup happens once per session, and a 100ms difference in completions is imperceptible. All four are fast enough that you won’t notice in daily use.

Ecosystem health³

We also looked at each project’s development velocity and community health metrics. A language server you rely on daily needs to keep up with Python’s evolution.

	Pyrefly	ty	Basedpyright	Zuban
GitHub stars	5.5K	17.8K	3.2K	1K
Contributors	165	40	188	5
License	MIT	MIT	MIT	AGPL-3.0
Releases (since Nov 2025)	17	29	10	9
Release cadence	~weekly	~twice weekly	~biweekly	~biweekly
Issues opened (90 days)	484	861	42	118
Issues closed (90 days)	497	743	20	114

ty and Pyrefly are shipping fast. Both are on a weekly release cadence or higher with high issue throughput. ty’s issue volume is notable: 861 issues opened in 90 days reflects both heavy adoption and active bug reporting. Pyrefly is closing more issues than it’s opening, a good sign for a beta project.

Response times are quick. In a spot-check of recent issues, ty and Pyrefly both had first responses from core maintainers within minutes to hours. Basedpyright’s maintainer responds quickly too, though at a lower volume. Zuban’s maintainer often replies within an hour.

What we chose

We bundled Pyrefly as Positron’s default Python language server.

The deciding factors:

It’s the best overall UX for data science. Hover docs were the cleanest. The type inference catches real bugs without requiring you to annotate everything, and the strictest type checking is off by default unless you configure it on. Notebook support has worked for months.
It has active development with strong backing. Meta has committed to making Pyrefly genuinely open-source and community-driven, with biweekly office hours and a public Discord. Development velocity is high.
No licensing complications for bundling.

It wasn’t a runaway winner. Basedpyright is more mature and feature-complete. ty has a lot of long-term potential, especially for ruff users and fans of the gradual guarantee, and is closing feature gaps fast. But for the specific use case of “Python data science in an IDE,” Pyrefly had the best balance of features, UX, and readiness.

How to switch

This space is competitive and moving fast, and you shouldn’t feel locked in. Positron makes it straightforward to switch language servers:

Open the Extensions view ().
Search for and install the language server you want to try (e.g., basedpyright, ty, or zuban).
Disable Pyrefly: search for pyrefly in Extensions, click Disable.
Reload the window with the command Developer: Reload Window.

Or, if you want to keep Pyrefly installed but prevent it from auto-activating, you can use the extensions.allowed setting:

{
    "extensions.allowed": {
        "meta.pyrefly": false,
        "*": true
    }
}

What’s next

ty is adding features at an aggressive pace and will likely close its remaining gaps. OpenAI’s acquisition of Astral adds resources but also uncertainty; it’s unclear how it will affect ty’s priorities. Pyrefly continues to improve its type checking and performance (a recent release noted 20% faster PyTorch benchmarks). Basedpyright tracks upstream Pyright closely and keeps shipping.

Both ty and Pyrefly have been receptive to PRs that improve the experience for Positron users, which suggests they care about working well across editors, not just VS Code. For example, both contribute hover, completions, and semantic highlighting in the Positron Console.

We’ll keep evaluating as these tools mature!

Want to try Positron? Download it here. It’s free and open source.

Footnotes

As of this post.↩︎
Zuban requires a multi-step manual startup, so we couldn’t measure this automatically.↩︎
As of this post.↩︎