Environment and Module Resolution

Environment and Module Resolution

How ty discovers Python environments, resolves first-party and third-party modules, and what environment variables affect behavior. Load when the user asks about import resolution, unresolved imports, virtual environments, or environment variables.

Table of Contents

1. Environment Discovery Flow
2. First-Party Module Resolution
3. Third-Party Module Resolution
4. Environment Variables
5. Python Version Resolution

Environment Discovery Flow

See environment-discovery.md for the full decision flowchart.

Summary of precedence:

1. --python flag or environment.python config (explicit override)
2. VIRTUAL_ENV env var (active virtual environment)
3. CONDA_PREFIX env var (active Conda environment; VIRTUAL_ENV takes precedence if both set)
4. .venv directory in project root or working directory
5. python3 or python binary in PATH

When using uv, Poetry, or other project management tools with a run subcommand, the virtual environment is typically activated automatically and detected via VIRTUAL_ENV.

First-Party Module Resolution

First-party modules are Python files that are part of your project source code.

Default search locations (checked in order, all included if they exist and are not packages):

• Project root (.)
• ./src — if it exists and contains no __init__.py or __init__.pyi
• ./<project-name> — if a ./<project-name>/<project-name> directory exists
• ./python — if it exists and is not a package

Override with environment.root:

[tool.ty.environment]
root = ["./app"]

environment.root accepts a list; paths are searched in priority order (first = highest priority).

Additional search paths that do not fit normal project layout:

[tool.ty.environment]
extra-paths = ["./shared/my-search-path"]

Third-Party Module Resolution

Third-party modules are resolved from the configured Python environment's site-packages directory.

ty requires a Python environment to resolve third-party imports. Without one, all third-party imports are unresolved.

Suppress specific unresolved import errors without fixing the environment:

[tool.ty.analysis]
# Suppress unresolved-import for all stubs packages
allowed-unresolved-imports = ["pandas-stubs.**"]

Replace an entire module's types with typing.Any:

[tool.ty.analysis]
# Treat pandas imports as Any (useful for partial stubs)
replace-imports-with-any = ["pandas.**", "numpy.**"]

PYTHONPATH env var adds directories to ty's search paths (same format as shell PATH).

Environment Variables

ty-defined variables

External variables read by ty

Python Version Resolution

See python-version-resolution.md for the full decision flowchart.

The target Python version affects:

• Allowed syntax (e.g., match statements require Python 3.10+)
• Standard library type definitions
• sys.version_info conditional branch evaluation
• Availability of symbols conditional on Python version

Version is resolved in this order when not explicitly set:

1. --python-version flag or environment.python-version config
2. Minimum version from project.requires-python in pyproject.toml
3. Inferred from activated or configured Python environment
4. Falls back to "3.14" (latest stable supported by ty)