Merging uv and ty: A Unified Astral Experience

Published: October 13, 2026 | Author: Sara Sklenka (@sarasklenka)

TL;DR: Astral has released an experimental integration between uv and ty. This brings first-class support for Python scripts (both in the CLI and editor) and introduces a consolidated uv check command.

This update represents a significant move toward a fully integrated Astral toolchain—one where a shared project understanding enables capabilities that were previously impossible.

The Astral Ecosystem

Astral focuses on creating high-performance Python tooling. Currently, the suite consists of:

• uv: The package manager.
• Ruff: The linter and formatter.
• ty: The type checker and language server.

Historically, these tools operated in isolation. While each tool is designed to be independently useful and compatible with the wider ecosystem, Astral's vision is that they should be exponentially more powerful when used in tandem.

The Synergy Logic

The integration is based on a simple premise: uv manages the environment and dependencies, while ty analyzes the source code.

$\text{Environment (uv)} + \text{Code Analysis (ty)} = \text{Integrated Intelligence}$

---

First-Class Support for Python Scripts

Thanks to PEP 723, Python scripts can now include inline metadata to specify their required Python version and dependencies.

While uv already used this metadata to create environments during execution, ty now leverages it for static analysis. Whether you are in your IDE or using the terminal, ty uses uv to prepare the specific environment required for each script.

Key Benefits for Scripts:

1. Isolated Requirements: Scripts within the same repo can have entirely different dependencies without conflicting.
2. Granular Checking: Each script is validated against its own specific declarations.
3. Enhanced Editor Experience: By syncing with uv, ty provides:
   • Intelligent completions
   • Hover documentation
   • Precise "Go to Definition" navigation

---

A Unified Checking Command: uv check

Astral is introducing uv check, a single entry point for project diagnostics. Currently, this provides a streamlined interface for ty.

The Goal: Eventually, uv check will incorporate Ruff, allowing developers to handle both linting and type checking with one command.

How it works:

Running uv check automatically handles environment preparation and dependency installation before invoking ty. It is designed to "just work." If you don't use it, your uv experience remains unchanged; the ty binary is simply installed upon the first call.

Command Variants:

• Workspace-wide: uv check (checks the whole workspace).
• Specific Package: uv check --package <name> (targets one package).
• All Packages: uv check --all-packages.
• Standalone Scripts: uv check --script example.py (uses PEP 723 requirements).

Consistency across environments: uv check references the ty version stored in your project's lockfile. This ensures that every developer and CI pipeline uses the exact same version of the type checker without needing separate version pins.

Note: The ty pre-commit hook now utilizes uv check internally to ensure the environment is correctly configured before every commit.

---

Technical Implementation & Setup

The integration relies on uv workspace metadata, which provides ty with a structured map of packages, dependencies, and the Python environment.

Security & Opt-in

Because installing dependencies involves executing third-party code, automatic environment setup for PEP 723 scripts is opt-in.

For VS Code Users:

1. Install uv and the ty extension.
2. Add the following to your settings.json:

{
  "ty.experimental.useUv": true
}

For CLI Users:

You can trigger the integration manually using an environment variable: TY_UV=scripts ty check

Minimum Requirements

• uv version 0.12.3 or newer
• ty version 0.0.76 or newer

---

What's Next?

This integration is currently experimental. Astral is seeking community feedback to refine the workflow.

Future Roadmap:

• Advanced Diagnostics: Developing checks that combine dependency knowledge with code analysis (e.g., identifying unused dependencies).
• Stability: Moving ty toward its official stable release.

Special thanks to Aria Desires and Micha Reiser for their contributions.