
ty's New Diagnostic Baselines: Turn On Strict Type Checking Without Fixing Every Legacy Error First
If you have ever tried to turn on strict type checking for an old Python codebase, you know the wall you hit. You run the checker. It prints 900 errors. Nobody has time to fix 900 errors before lunch, so the checker gets turned off again, and the codebase stays untyped forever.
Astral's ty, the Rust-based type checker from the team behind uv and ruff, shipped a preview feature in v0.0.93 (October 28, 2026) that is built to fix exactly that problem: diagnostic baselines. You record every error ty finds today, and from then on, only new errors show up. The old ones stay in a file, out of your way, until you get around to them.
What a baseline actually does
A baseline is not a way to silence ty. It is a snapshot of every diagnostic ty currently reports, saved to a file. Every future run of ty check compares its fresh results against that snapshot and filters out anything that matches. New errors — ones that were not in the snapshot — still fail the check. Your editor keeps showing the baselined ones too, just as hints instead of hard errors, so they are not invisible, just non-blocking.
That is a meaningfully different approach from "just ignore everything and clean up later." You are not lowering your standards for new code. You are drawing a line under the old code and holding the line from that point on.
Setting it up
First, tell ty where to keep the baseline, in pyproject.toml:
[tool.ty]
baseline = "ty-baseline.json"Now imagine a small, imperfect module that has been sitting untyped in your codebase for two years:
# pricing.py
def discount(price: float, percent: int) -> float:
return price - (price * percent / 100)
def apply_discounts(prices: list[float]) -> list[float]:
# percent was meant to be an int, but this call passes a string
return [discount(p, "10") for p in prices]
class Order:
def __init__(self, total: float):
self.total = total
def summarize(order: Order | None) -> str:
# order can be None here, but .total is accessed without a check
return f"Total: {order.total}"Run ty check on this today, before any baseline exists, and it reports both real bugs: a str passed where discount expects an int, and .total accessed on a value that can be None. On a real codebase, multiply that by a few hundred.
Record the current state as the baseline:
# See everything ty currently flags
ty check
# Snapshot every one of those diagnostics into ty-baseline.json
ty check --update-baseline
# Commit the baseline with your code — it's part of the config now
git add ty-baseline.json pyproject.toml
git commit -m "Adopt ty with a diagnostic baseline"Run ty check again right after that, and it comes back clean — both of those pre-existing errors are now in the baseline, so they are filtered out of the CLI output. Your editor's ty integration still surfaces them as low-priority hints, so nobody forgets they exist; they just stop blocking CI.
Now introduce a genuinely new bug somewhere else in the file:
def apply_tax(total: float, tax: float) -> float:
return total + (total + tax) # should be total * (1 + tax), not + tax... but that's a logic bug, not a type one
def format_receipt(order: Order) -> str:
return order.totals # typo: Order has `total`, not `totals`ty check this time reports exactly one error — the typo on order.totals — because that diagnostic was never in the baseline. The two older errors in pricing.py stay quiet. That is the whole feature: it narrows your attention to what actually changed.
How this compares to the mypy "ratchet" pattern
Teams adopting mypy --strict on a legacy codebase have long used a trick sometimes called a ratchet: count the errors today, store that count, and fail CI only if the count goes up. It works, and it is simple enough to write in an afternoon. Here is a typical version:
#!/usr/bin/env python3
# scripts/mypy_ratchet.py
import json
import subprocess
import sys
from pathlib import Path
BASELINE_FILE = Path("mypy-baseline.json")
def count_errors() -> int:
result = subprocess.run(
["mypy", "--strict", ".", "--no-error-summary"],
capture_output=True,
text=True,
)
return len([line for line in result.stdout.splitlines() if ": error:" in line])
def main() -> int:
current = count_errors()
if not BASELINE_FILE.exists():
BASELINE_FILE.write_text(json.dumps({"error_count": current}))
print(f"Baseline created with {current} errors.")
return 0
allowed = json.loads(BASELINE_FILE.read_text())["error_count"]
if current > allowed:
print(f"FAIL: {current} mypy errors, baseline allows {allowed}.")
return 1
if current < allowed:
BASELINE_FILE.write_text(json.dumps({"error_count": current}))
print(f"Baseline tightened: {allowed} -> {current} errors.")
print(f"OK: {current} errors, within baseline of {allowed}.")
return 0
if __name__ == "__main__":
sys.exit(main())This works, but it has a real gap: it ratchets on a count, not on the specific diagnostics. If you fix one error and accidentally introduce a different one in the same commit, the count stays flat and the script says everything is fine — even though a brand-new bug just slipped in disguised as the one you fixed. ty's baseline is keyed to the individual diagnostic (its location and rule), so swapping one error for another is visible: the old one is still filtered as expected, and the new one is flagged as new, because it genuinely is new.
The ratchet script is still the right tool if you are on mypy and don't want to switch checkers. But if you are already looking at ty, or considering a move, the baseline feature gets you the same "don't let it get worse" guarantee with much finer precision, for free, built into the tool itself.
Worth knowing before you adopt it
- This is a preview feature. Astral's own release notes say the baseline file format may change while it's in preview — don't build tooling on the exact shape of
ty-baseline.jsonyet. - A baseline hides errors from CI, it does not fix them. Treat it as a way to adopt type checking today, not a replacement for eventually paying down the debt.
- Baselining an error you introduce after adoption just to make a build pass defeats the point — reserve
--update-baselinefor the initial adoption and for deliberate, reviewed decisions to defer something, not as a routine escape hatch.
If your team has wanted strict type checking for a while but keeps bouncing off the size of the existing error list, this is the smallest possible first step: run the baseline command once, commit the file, and start holding the line on everything written from today forward.
Try it: run ty check --update-baseline on one of your own repos and see how many errors it swallows on day one — that number is a pretty honest measure of how much type-safety debt you're sitting on.

Experienced DevOps Engineer proficient in Python, Docker, Kubernetes, CI/CD, and cloud technologies. Specialized in automating processes and building scalable infrastructure for seamless development and deployment.


