{"id":7428,"library":"monkeytype","title":"MonkeyType","description":"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.","status":"active","version":"23.3.0","language":"en","source_language":"en","source_url":"https://github.com/Instagram/MonkeyType","tags":["typing","type annotations","static analysis","code generation","runtime analysis","developer tools"],"install":[{"cmd":"pip install monkeytype","lang":"bash","label":"Install MonkeyType"}],"dependencies":[{"reason":"Required for applying type stubs to code files and performing code transformations.","package":"libcst"}],"imports":[{"note":"Used for programmatic tracing of code blocks.","symbol":"trace","correct":"from monkeytype import trace"},{"note":"Base class for custom MonkeyType configurations. `DefaultConfig` is also available for extending default behavior.","symbol":"Config","correct":"from monkeytype.config import Config"}],"quickstart":{"code":"import os\n\n# my_module.py\ndef add(a, b):\n    return a + b\n\ndef concatenate(s1, s2):\n    return s1 + s2\n\n# To run this module with MonkeyType tracing\nif __name__ == \"__main__\":\n    # Simulate usage to collect type traces\n    add(1, 2)\n    add(1.5, 2.5)\n    concatenate(\"hello\", \"world\")\n    concatenate([\"a\"], [\"b\", \"c\"])\n\n# --- Steps to run from your terminal ---\n# 1. Save the above code as 'my_module.py'.\n# 2. Run your module under MonkeyType to collect traces:\n#    $ monkeytype run my_module.py\n# 3. Generate a stub file (.pyi) from the collected traces:\n#    $ monkeytype stub my_module > my_module.pyi\n# 4. Or, apply type annotations directly to your source file (modifies in-place):\n#    $ monkeytype apply my_module\n#\n# Note: Traces are stored in a SQLite database (monkeytype.sqlite3) by default.","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.7+ and MonkeyType to the latest version.","message":"MonkeyType 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.","severity":"breaking","affected_versions":"<22.2.0"},{"fix":"Manually review and refine generated type annotations for correctness and abstraction.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Wrap module-level execution code in `if __name__ == '__main__':` blocks.","message":"Running `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade MonkeyType to version 22.2.0 or newer.","cause":"Incompatibility with internal changes to Python 3.9's `typing` module.","error":"AttributeError: '__args__' when generating stubs on Python 3.9"},{"fix":"Upgrade MonkeyType to version 22.2.0 or newer.","cause":"Incompatibility with Python 3.9's handling of `Union` types during call trace collection.","error":"AttributeError: '_SpecialForm' object has no attribute '__name__' in collecting traces with Union types"},{"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.","cause":"`libcst` is a mandatory dependency for applying type stubs and code transformations, and it might be missing or an incompatible version.","error":"ModuleNotFoundError: No module named 'libcst' or errors applying stubs."},{"fix":"Upgrade MonkeyType to version 23.3.0 or newer. Additionally, ensure your `monkeytype_config.py` is free of syntax or runtime errors.","cause":"Earlier versions of MonkeyType had issues with configuration loading logic that could prematurely catch errors in custom config files.","error":"TypeError/ValueError at import time of a custom config and replacing with a generic “invalid value” message"}]}