---
last_review_date: 2025-05-22
---

# Type Checking With Sorbet

The majority of the code in Homebrew is written in Ruby which is a dynamic language. To avail the benefits of static type checking, we have set up [Sorbet](https://sorbet.org/) in our codebase which provides the benefits of static type checking to dynamic languages like Ruby.

The [Sorbet Documentation](https://sorbet.org/docs/overview) is a good place to get started if you want to dive deeper into Sorbet and its abilities.

## Sorbet in the Homebrew codebase

### Inline type annotations

The `sig` method is used to annotate method signatures. Here's a simple example:

```ruby
class MyClass
  sig { params(name: String).returns(String) }
  def my_method(name)
    "Hello, #{name}!"
  end
end
```

With `params` we specify that there is a parameter `name` which must be a `String`, and with `returns` we specify that this method always returns a `String`.

For more information on how to express more complex types, refer to the official documentation:

- [Method Signatures](https://sorbet.org/docs/sigs)
- [Class Types](https://sorbet.org/docs/class-types)
- [Nilable Types](https://sorbet.org/docs/nilable-types)
- [Union Types](https://sorbet.org/docs/union-types)

### Ruby interface files (`.rbi`)

[RBI files](https://sorbet.org/docs/rbi) help Sorbet learn about constants, ancestors and methods defined in ways it doesn't understand natively. We can also create an RBI file to help Sorbet understand dynamic definitions. Some of these files are automatically generated (see the next section) and some are manually written, e.g. [`on_system.rbi`](https://github.com/Homebrew/brew/blob/HEAD/Library/Homebrew/on_system.rbi).

There are also a very small number of files that Homebrew loads before `sorbet-runtime`, such as `utils/gem_setup.rb`. Those files cannot have type signatures alongside the code itself, so RBI files are used there instead to retain static type checking.

### The [`Library/Homebrew/sorbet`] directory

[`Library/Homebrew/sorbet`]: https://github.com/Homebrew/brew/tree/HEAD/Library/Homebrew/sorbet

The `rbi` directory contains the Ruby Interface (`.rbi`) files, some auto-generated by running `brew typecheck --update` and some maintained by hand:

- `gems`: RBI files for all gems are generated using [Tapioca](https://github.com/Shopify/tapioca#tapioca).
- `dsl`: RBI files auto-generated by our [Tapioca compilers](https://github.com/Homebrew/brew/tree/HEAD/Library/Homebrew/sorbet/tapioca/compilers).
- `annotations`: handwritten refinements for gem interfaces generated elsewhere.
- `shims`: handwritten interfaces for dynamically defined Homebrew code and other gaps.
- `upstream.rbi`: temporary workarounds for upstream Sorbet issues.

The `tapioca` directory contains configuration files and compilers for Tapioca, allowing Sorbet to type check the dynamically generated components of the codebase.

The `config` file is a newline-separated list of arguments to pass to `srb tc`, the same as if they'd been passed on the command line. Arguments in the config file are always passed first, followed by arguments provided on the command line. We use it to ignore e.g. gem directories which we do not wish to type check.

## Using `brew typecheck`

Every Ruby file in the codebase has a magic `# typed: <level>` comment at the top, where `<level>` is one of [Sorbet's strictness levels](https://sorbet.org/docs/static#file-level-granularity-strictness-levels), usually `false`, `true` or `strict`. The `false` files only report errors related to the syntax, constant resolution and correctness of the method signatures, but no type errors. Our long-term goal is to move all `false` files to `true` and start reporting type errors on those files as well. Therefore, when adding new files, you should ideally mark it with `# typed: true` and work out any resulting type errors.

When run without any arguments, `brew typecheck` will run considering the strictness levels set in each of the individual Ruby files in the core Homebrew codebase. However, when run on a specific file or directory, more errors may show up since Sorbet cannot resolve constants defined outside the scope of the specified file. These problems can be solved with RBI files. Currently `brew typecheck` provides `--quiet`, `--file`, `--dir` and `--ignore` options, but you can explore more options with `srb tc --help` and pass them with `srb tc`.

## Resolving type errors

Sorbet reports type errors along with an error reference code, which can be used to look up more information on how to debug the error, or what causes the error in the [Sorbet Documentation](https://sorbet.org/docs/overview). Here's how to debug some common type errors:

- Using `T.reveal_type`: in files which are `true` or higher, by wrapping a variable or method call in `T.reveal_type`, Sorbet will show us what type it thinks that variable has in the output of `srb tc`. This is particularly useful when writing [method signatures](https://sorbet.org/docs/sigs) and debugging. Make sure to remove this line from your code before committing your changes, since this is just a debugging tool.

- One of the most frequent errors that we've encountered is `7003: Method does not exist.` Since Ruby is a very dynamic language, methods can be defined in ways Sorbet cannot see statically. In such cases, check if the method exists at runtime; if not, then Sorbet has caught a future bug! But, it is also possible that even though a method exists at runtime, Sorbet cannot see it. In such cases, we use [`.rbi` files](#ruby-interface-files-rbi).

- Since Sorbet does not automatically assume that `Kernel` is to be included in modules, we may encounter many errors while trying to use methods like `puts`, `ohai`, `odebug` etc. There are generally two approaches to fixing this:

  - If you are using `module_function` but never run `include ModuleName` anywhere, remove the `module_definition` and convert all methods to class methods (prepend the name with `self.`).
  - If you do include the module elsewhere, add a `requires_ancestor` to the module defining what types of classes this module can be included in. This may be as simple as a `requires_ancestor { Kernel }`, which most classes are descended from.

- The tips above are very generic and apply to lots of cases. For some common gotchas when using Sorbet, refer to the [Sorbet Error Reference](https://sorbet.org/docs/error-reference) and [FAQ](https://sorbet.org/docs/faq).
