A Very (!) Early Play With Astral's Red Knot Static Type Checker

# Setting up the Red Knot Type Checker

Red Knot is an extremely fast Python type checker developed by the Ruff team. It's designed to prioritize good type inference even in unannotated code and aims to avoid false positives. It's currently under active development and is not yet officially released, but you can try it out from the source.

## Prerequisites

- Rust toolchain installed (https://rustup.rs/)
- Git

## Step 1: Clone the Ruff repository

```bash
git clone https://github.com/astral-sh/ruff.git
cd ruff
```

## Step 2: Build Red Knot

```bash
cargo build --bin red_knot --release
```

This will produce a binary at `target/release/red_knot`.

## Step 3: Basic Usage

The Red Knot binary provides a `check` command that works similar to tools like mypy:

```bash
# Check files or directories (from project root)
./target/release/red_knot check path/to/your/python/files

# Check with python version specified
./target/release/red_knot check --python-version 3.11 path/to/your/python/files

# Set severity levels for specific rules
./target/release/red_knot check --error call-non-callable --warn call-possibly-unbound-method path/to/your/python/files

# Watch mode (automatically rechecks when files change)
./target/release/red_knot check --watch path/to/your/python/files
```

## Step 4: Configuration

Red Knot can be configured in your project's `pyproject.toml` file. Here's an example configuration:

```toml
[tool.knot]
# Environment settings
environment.python-version = "3.11"  # Target Python version
environment.python = ".venv"  # Path to Python environment (for third-party imports)
environment.extra-paths = ["path/to/extra/modules"]  # Additional module search paths

# Terminal settings
terminal.output-format = "full"  # "full" or "concise"
terminal.error-on-warning = true  # Exit with error code on warnings

# Configure rule severities
rules.call-non-callable = "error"
rules.call-possibly-unbound-method = "warn"
```

## Migrating from mypy to Red Knot

Since Red Knot is still in development, migrating from mypy should be done with caution:

1. **Run both in parallel**: Keep mypy running while you test Red Knot on your codebase
2. **Configure Python version**: Make sure to set the same Python version as in your mypy config
3. **Environment setup**: Configure virtual environments correctly to ensure third-party imports work
4. **Analyze differences**: Red Knot may produce different results than mypy as noted in its README (by design)

### Comparing Red Knot with mypy

For a side-by-side comparison of mypy and Red Knot on your codebase, you can use the mypy_primer tool (forked by the Ruff team):

```bash
# Install mypy_primer
uv tool install "git+https://github.com/astral-sh/mypy_primer.git@add-red-knot-support"

# Run comparison
mypy_primer --repo /path/to/ruff --old-tool mypy --new-tool red-knot
```

## Limitations

- Red Knot is still under development and may not support all mypy features
- Documentation is limited as the project is not officially released
- The API and CLI interface may change in future versions

% ./target/release/red_knot
An extremely fast Python type checker.

Usage: red_knot <COMMAND>

Commands:
  check    Check a project for type errors
  server   Start the language server
  version  Display Red Knot's version
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Check a project for type errors

Usage: red_knot check [OPTIONS] [PATH]...

Arguments:
  [PATH]...  List of files or directories to check [default: the project root]

Options:
      --project <PROJECT>              Run the command within the given project directory
      --python <PATH>                  Path to the Python installation from which Red Knot resolves type information and third-party dependencies
      --typeshed <PATH>                Custom directory to use for stdlib typeshed stubs
      --extra-search-path <PATH>       Additional path to use as a module-resolution source (can be passed multiple times)
      --python-version <VERSION>       Python version to assume when resolving types [possible values: 3.7, 3.8, 3.9, 3.10, 3.11, 3.12, 3.13]
  -v, --verbose...                     Use verbose output (or `-vv` and `-vvv` for more verbose output)
      --output-format <OUTPUT_FORMAT>  The format to use for printing diagnostic messages [possible values: full, concise]
      --error-on-warning               Use exit code 1 if there are any warning-level diagnostics
      --exit-zero                      Always use exit code 0, even when there are error-level diagnostics
  -W, --watch                          Watch files for changes and recheck files related to the changed files
  -h, --help                           Print help (see more with '--help')

Enabling / disabling rules:
      --error <RULE>   Treat the given rule as having severity 'error'. Can be specified multiple times.
      --warn <RULE>    Treat the given rule as having severity 'warn'. Can be specified multiple times.
      --ignore <RULE>  Disables the rule. Can be specified multiple times.

[tool.knot]
# Environment settings
environment.python-version = "3.11"  # Target Python version
environment.python = ".venv"  # Path to Python environment (for third-party imports)
# environment.extra-paths = ["path/to/extra/modules"]  # Additional module search paths

# Terminal settings
terminal.output-format = "full"  # "full" or "concise"
terminal.error-on-warning = true  # Exit with error code on warnings

# Configure rule severities
rules.call-non-callable = "error"
rules.call-possibly-unbound-method = "warn"

error: lint:unsupported-operator
   --> /Users/michael/git/mcpunk/mcpunk/util.py:125:40
    |
124 | def short_me_out(x: int | None) -> bool:
125 |     _ = [z for z in [] if x is None or 1 <= x]
    |                                        ^^^^^^ Operator `<=` is not supported for types `int` and `None`, in comparing `Literal[1]` with `int | None`
126 |     return False