Skip to main content

Repo PyPI license PyPI version Code style: ruff uv

typecheck-runner

A unified way to run globally installed typecheckers against a specified virtual environment.

Overview

I prefer to invoke globally managed type checkers against specified virtual environments. For cases where python versions are checked against (with, for example tox or nox), this prevents each virtual environment from having to contain a type checker. Each type checker (mypy, pyright, basedpyright, ty, and pyrefly) has it's own particular flags to specify the python executable and the python version. typecheck-runner unifies these flags. Also, by default, typecheck-runner invokes the type checker using uvx, which installs the type checker if needed.

Usage

Install into virtual environment

The easiest way to use typecheck-runner is to install it into the virtual environment you'd like to test against using something like

pip install typecheck-runner

from the virtual environment of interest. To invoke a type checker against the virtual environment, assuming the python executable of the virtual environment is located at /path/to/venv/bin with python version 3.13, use

typecheck-runner --check mypy
# runs: uvx mypy --python-version=3.13 --python-executable=/path/to/venv/bin

Where the commented line shows the command run. Specifying --no-uvx will instead invoke the type checker without uvx, so the type checker must already be installed.

You can specify multiple checkers with multiple --check flags. To specify options to uvx for each checker, pass options after --uvx-delimiter which defaults to --. For example:

typecheck-runner --check "mypy --verbose -- --reinstall"
# runs: uvx --reinstall mypy --verbose

You can specify uvx options to all checkers using the --uvx-options flag.

Specify virtual environment

You can also use a globally installed typecheck-runner and specify which virtual environment to test over using --venv or --infer-venv options. For example, you can use:

uvx typecheck-runner --venv .venv --check mypy
# run for example (if .venv current directory with version 3.14)
#   uvx mypy --python-version=3.14 --python-executable=.venv/bin/python

Using --infer-venv will attempt to infer the virtual environment from, in order, environment variables VIRTUAL_ENV, CONDA_PREFIX, and finally .venv in current directory.

Options

usage: typecheck-runner [-h] [--version] [-c CHECKERS]
                        [--python-executable PYTHON_EXECUTABLE]
                        [--python-version PYTHON_VERSION] [--no-python-executable]
                        [--no-python-version] [--venv VENV] [--infer-venv]
                        [--constraints CONSTRAINTS] [-v] [--stdout] [--allow-errors]
                        [--fail-fast] [--dry-run] [--no-uvx] [--uvx-options UVX_OPTIONS]
                        [--uvx-delimiter UVX_DELIMITER]
                        [args ...]

Run executable using uvx.

positional arguments:
  args                  Extra files/arguments passed to all checkers.

options:
  -h, --help            show this help message and exit
  --version             Display version.
  -c, --check CHECKERS  Checker to run. This can be a string with options to the
                        checker. For example, ``--check "mypy --verbose"`` runs the
                        checker the command ``mypy --verbose``. Options after
                        ``uvx_delimiter`` (default ``"--"``, see ``--uvx-delimiter``
                        options) are treated as ``uvx`` options. For example, passing
                        ``--check "mypy --verbose -- --reinstall"`` will run ``uvx
                        --reinstall mypy --verbose``. Can be specified multiple times.
                        Note that for checkers `ty` and `pyrefly`, the subcommand
                        ``check`` will be added if ``--check=ty`` or
                        ``--check=pyrefly``. To pass extra options, explicitly pass
                        ``check``. For example, ``--check='ty check --verbose'``.
  --python-executable PYTHON_EXECUTABLE
                        Path to python executable. Defaults to ``sys.executable``. This
                        is passed to ``--python-executable`` (mypy), ``--pythonpath`` in
                        ((based)pyright), ``--python`` (ty), ``--python-interpreter-
                        path`` (pyrefly), and ignored for pylint.
  --python-version PYTHON_VERSION
                        Python version (x.y) to typecheck against. Defaults to
                        ``{sys.version_info.major}.{sys.version_info.minor}``. This is
                        passed to ``--pythonversion`` in pyright and ``--python-
                        version`` otherwise.
  --no-python-executable
                        Do not infer ``python_executable``
  --no-python-version   Do not infer ``python_version``.
  --venv VENV           Use specified vitualenvironment location
  --infer-venv          Infer virtual environment location. Checks in order environment
                        variables ``VIRTUAL_ENV``, ``CONDA_PREFIX``, directory
                        ``.venv``.
  --constraints CONSTRAINTS
                        Constraints (requirements.txt) specs for checkers. Can specify
                        multiple times. Passed to ``uvx --constraints=...``.
  -v, --verbose         Set verbosity level. Pass multiple times to up level.
  --stdout              logger information to stdout
  --allow-errors        If passed, return ``0`` regardless of checker status.
  --fail-fast           Exit on first failed checker. Default is to run all checkers,
                        even if they fail.
  --dry-run             Perform dry run.
  --no-uvx              If ``--no-uvx`` is passed, assume typecheckers are in the
                        current python environment. Default is to invoke typecheckers
                        using `uvx`.
  --uvx-options UVX_OPTIONS
                        Extra options to pass to ``uvx``. Note that you may have to
                        escape the first option. For example, ``--uvx-options
                        "\--verbose --reinstall"
  --uvx-delimiter UVX_DELIMITER
                        Delimiter between typechecker command arguments and ``uvx``
                        arguments. See ``--check`` option.

Status

This package is actively used by the author. Please feel free to create a pull request for wanted features and suggestions!

Installation

Use one of the following

pip install typecheck-runner
uv pip install typecheck-runner
uv add typecheck-runner
...

What's new?

See changelog.

License

This is free software. See LICENSE.

Any other stuff to mention....

Contact

The author can be reached at wpk@nist.gov.

Credits

This package was created using Cookiecutter with the usnistgov/cookiecutter-nist-python template.

Metadata

Release files for typecheck-runner 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for typecheck-runner 0.2.1
File Size Uploaded Provenance Actions
typecheck_runner-0.2.1.tar.gz 19.4 kB With provenance Details for typecheck_runner-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for typecheck-runner 0.2.1
File Interpreter ABI Platform Actions
typecheck_runner-0.2.1-py3-none-any.whl Python 3 none any Details for typecheck_runner-0.2.1-py3-none-any.whl

Total release size: 30.2 kB

Release files / typecheck_runner-0.2.1.tar.gz

Download URL typecheck_runner-0.2.1.tar.gz
Size 19.4 kB
Tags Source
SHA-256 checksum
How to use checksums
87917e54dc48203b09ebef531ac095ee2d978f25cb253a3e6758b36141fbf93d
BLAKE2b-256 checksum
How to use checksums
3585a3a64d393ddaf73ccc301442aa7202193e2fff0360f050606c6615dad0d2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

Release files / typecheck_runner-0.2.1-py3-none-any.whl

Download URL typecheck_runner-0.2.1-py3-none-any.whl
Size 10.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e728eee652efc1da5cd484cd3ecc4fad1466bafa6540e566b420ffa8c9581c22
BLAKE2b-256 checksum
How to use checksums
37bf070fbd791f1e8257022de40a66da92ce947a235cd9beea480589f74d01a9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

Security for typecheck-runner 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for typecheck_runner-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page