monkeytype

library23.3.0pypypi✓ verified 85d ago

MonkeyType is a Python library that automatically generates type annotations from sampled production types. It uses Python's `sys.setprofile` hook to record the types of function arguments, return values, and yield values at runtime. Based on this collected data, it can generate stub files (`.pyi`) or apply draft type annotations directly to existing Python code. The current stable version is 23.3.0, with a history of regular updates focusing on Python version compatibility and annotation accuracy.

type-stubs testing

pip install monkeytype

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONKEYTYPE

monkeytype

type-stubspythonv23.3.0

Install

2.6s avg

Import

97ms

Disk

32MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v23.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.102s · 32.6MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.6s · import 0.092s · 34MB

32MB installed

● package 32MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

trace

✓ from monkeytype import trace

Used for programmatic tracing of code blocks.

Config

✓ from monkeytype.config import Config

Base class for custom MonkeyType configurations. `DefaultConfig` is also available for extending default behavior.

The quickstart demonstrates the typical workflow: first, run your Python code with `monkeytype run` to collect runtime type traces. Then, use `monkeytype stub` to generate a `.pyi` stub file with annotations, or `monkeytype apply` to inject the annotations directly into your Python source file.

import os # my_module.py def add(a, b): return a + b def concatenate(s1, s2): return s1 + s2 # To run this module with MonkeyType tracing if __name__ == "__main__": # Simulate usage to collect type traces add(1, 2) add(1.5, 2.5) concatenate("hello", "world") concatenate(["a"], ["b", "c"]) # --- Steps to run from your terminal --- # 1. Save the above code as 'my_module.py'. # 2. Run your module under MonkeyType to collect traces: # $ monkeytype run my_module.py # 3. Generate a stub file (.pyi) from the collected traces: # $ monkeytype stub my_module > my_module.pyi # 4. Or, apply type annotations directly to your source file (modifies in-place): # $ monkeytype apply my_module # # Note: Traces are stored in a SQLite database (monkeytype.sqlite3) by default.

monkeytype --version

Debug

Known issues

breakingMonkeyType dropped support for Python 3.6 in version 22.2.0. Users on older Python versions must upgrade their environment or use an older MonkeyType version.

fix

Upgrade Python to 3.7+ and MonkeyType to the latest version.

affects: <22.2.0

gotchaThe annotations generated by MonkeyType are derived from concrete runtime types and may not always reflect the full intended capability of functions (e.g., `List` instead of `Sequence`). They should be treated as a first draft requiring human review and refinement.

fix

Manually review and refine generated type annotations for correctness and abstraction.

affects: All versions

gotchaWhen using `monkeytype run <script.py>`, traces are *not* recorded for the entry-point script (`<script.py>`) itself, only for modules it imports. To annotate the entry point, a small wrapper script that imports and calls functions from the target script is needed.

fix

For `script.py`, create `run_script.py`: `from script import main; main()`, then `monkeytype run run_script.py` and target `script` for stubs/apply.

affects: All versions

gotchaRunning `monkeytype stub` or `monkeytype apply` on a module with import-time side effects will trigger those side effects because MonkeyType must import your code. For 'executable' modules, ensure execution code is protected by `if __name__ == '__main__'` to prevent unintended execution.

fix

Wrap module-level execution code in `if __name__ == '__main__':` blocks.

affects: All versions

Errors

Common errors & fixes

AttributeError: '__args__' when generating stubs on Python 3.9

Incompatibility with internal changes to Python 3.9's `typing` module.

fix

Upgrade MonkeyType to version 22.2.0 or newer.

AttributeError: '_SpecialForm' object has no attribute '__name__' in collecting traces with Union types

Incompatibility with Python 3.9's handling of `Union` types during call trace collection.

fix

Upgrade MonkeyType to version 22.2.0 or newer.

ModuleNotFoundError: No module named 'libcst' or errors applying stubs.

`libcst` is a mandatory dependency for applying type stubs and code transformations, and it might be missing or an incompatible version.

fix

Ensure `libcst` is installed and meets the required version (`libcst>=0.3.5` for MonkeyType 20.5.0+). Running `pip install monkeytype` typically handles this.

TypeError/ValueError at import time of a custom config and replacing with a generic “invalid value” message

Earlier versions of MonkeyType had issues with configuration loading logic that could prematurely catch errors in custom config files.

fix

Upgrade MonkeyType to version 23.3.0 or newer. Additionally, ensure your `monkeytype_config.py` is free of syntax or runtime errors.

Upgrade

Version history

23.3.0latest on PyPI · released Mar 20, 2023

Audit

Dependencies

libcstrequiredRequired for applying type stubs to code files and performing code transformations.

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Instagram/MonkeyType ↗

packagehttps://pypi.org/project/monkeytype/ ↗

homepagehttps://monkeytype.readthedocs.io/ ↗