uv Script Runs but ty Cannot Resolve Imports? Match the Script Environment

Give the checker the environment that belongs to the script

For a standalone file with PEP 723 metadata, the new entry point is uv check --script example.py. The experimental integration announced by Astral on October 13 requires uv 0.12.3 or later and ty 0.0.76 or later.

uv check --script example.py

Astral’s announcement describes separate environments for scripts, allowing their dependency and Python requirements to differ from those of the surrounding project. Replace the example filename with the file you want to check.

That matters because successful execution does not tell you where a separate checker is looking. ty’s module discovery documentation says third-party imports are resolved through its configured Python environment. In ordinary project discovery, an active virtual environment or a project’s .venv can supply that environment. A package installed for uv’s script runner need not be visible there.

Declare what the file needs, rather than relying on a nearby project

PEP 723 stores dependency metadata in comments inside the Python file. uv can create and update that metadata for you. For a new file, this documentation-based example declares rich and then checks the script:

uv init --script demo.py --python 3.12
uv add --script demo.py rich
uv check --script demo.py

The initialization step is for creating a new script; an existing file does not need to be recreated. The add --script step records a requirement in the file, while the final command uses those requirements for checking.

The distinction from a project dependency is deliberate. According to the uv script guide, running a file with inline metadata ignores the surrounding project’s dependencies. If a standalone script needs a package, declare it there even when a neighboring project already uses it.

Enable script integration in the ty extension

With uv and the ty VS Code extension installed, add this entry to VS Code’s settings.json:

{
  "ty.experimental.useUv": "scripts"
}

The editor settings reference distinguishes scripts, which creates and updates standalone script environments, from on, which also uses uv for project discovery. Restart the editor after changing this initialization option.

Restricted Mode disables the integration. Preparing an environment includes installing dependencies, so this is more than reading comments. The setting also belongs to ty: it does not reconfigure Pylance. If a diagnostic remains, check which extension produced it before assuming the new environment was ignored.

Once imports resolve, read the remaining diagnostic

An environment correction can expose a real type error instead of making every warning disappear. Use the symptom to choose the next check:

Keep existing lint and test steps in place. The announcement positions Ruff support as future work; the new uv check entry point currently runs ty. Its immediate benefit is a better match between a standalone file’s declared dependencies and the environment used to examine its code.