Introduction
TransformerLens is a Python library designed for mechanistic interpretability of GPT-style language models. Its primary objective is to enable researchers to reverse-engineer the algorithms embedded within trained models by exposing their internal activations. The library was created by Neel Nanda and is maintained by Bryce Meyer and Jonah Larson. It builds upon the principles established by Anthropic’s Garcon tool, aiming to provide a robust framework for exploratory analysis of model internals without requiring large-scale computational resources or industry-level infrastructure.
TransformerLens facilitates this by allowing users to load over 15,000 open-source models spanning 140+ architecture families. The library preserves raw HuggingFace weights by default, ensuring logits and activations match those produced by HuggingFace models, though compatibility modes exist for legacy HookedTransformer behaviors.
The library’s design prioritizes rapid experimentation and short feedback loops, making it accessible for researchers working with smaller models in environments like Colab notebooks.
How It Works
Users can initialize a bridge instance using TransformerBridge.boottransformers(), specifying a model name (e.g., gpt2) and device (CPU/GPU). Once loaded, the bridge allows users to execute the model while caching internal activations via the runwithcache() method. This cached data can then be accessed, modified, or replaced during runtime, enabling interventions such as activation patching or removal.
The library supports two primary modes for model loading: native HuggingFace weights and legacy HookedTransformer compatibility. By default, TransformerLens preserves raw HuggingFace weights, ensuring numerical consistency with the original model outputs. Users can enable compatibility mode via bridge.enablecompatibilitymode() to replicate HookedTransformer’s default behaviors, such as folding LayerNorm and centering weights.
TransformerLens also includes experimental support for non-transformer architectures, such as state-space models (SSMs) like Mamba-1 and Mamba-2. Bridge adapters for these models provide forward-pass equivalence to HuggingFace implementations, hook-based introspection of projection activations, and stateful generation with cache-aware decoding.
For example, researchers can define functions to edit activations dynamically, ablate specific components, or inject synthetic patterns to test hypotheses about model behavior.
Use Cases
TransformerLens has been instrumental in advancing research across several domains within mechanistic interpretability. One key application is circuit discovery, where researchers identify and characterize functional components within models that correspond to specific cognitive or computational tasks. For instance, studies have used TransformerLens to uncover induction heads in GPT-2, which are hypothesized to play a role in in-context learning.
Another prominent use case is activation patching, a technique where researchers modify internal activations to probe their causal roles in model outputs. This method has been applied to study phenomena such as grokking—where models abruptly acquire new capabilities—and to dissect emergent behaviors like linear world representations in smaller models. TransformerLens provides the tools to cache, edit, and replace activations at arbitrary layers, enabling precise interventions that reveal how models process information.
The library has also facilitated research into neuron and circuit attribution, where individual neurons or groups of neurons are analyzed for their contributions to specific tasks. TransformerLens supports these analyses through its attribution-patching substrate, which allows researchers to systematically ablate or perturb components while monitoring changes in model behavior.
Beyond transformers, TransformerLens has been adapted to study hybrid architectures, such as those combining transformers with state-space models (e.g., Qwen3.5 or GraniteMoeHybrid). This cross-architecture support is particularly valuable as the field explores alternatives to traditional transformer designs.
User-contributed examples further illustrate the library’s versatility. Projects such as the replication of induction heads and decision transformer interpretability demonstrate how TransformerLens can be integrated into broader research pipelines.
Key Features & Capabilities
TransformerLens provides a comprehensive suite of tools tailored for mechanistic interpretability research. One of its standout features is activation caching, which allows users to store intermediate activations during model execution. These cached activations can be accessed and manipulated in real-time, enabling dynamic interventions such as zeroing out specific neurons or injecting synthetic patterns. This capability is foundational for techniques like activation patching and circuit ablation.
The library includes hook-based introspection, which lets researchers attach custom functions to model components (e.g., attention heads, MLP layers) to monitor or modify their behavior. Hooks can be applied at any layer or sub-layer, providing granular control over the model’s computational graph. For example, researchers can use hooks to trace the flow of information through attention mechanisms or to isolate the contributions of individual neurons to specific outputs.
The library’s model bridge system unifies access to a diverse range of architectures, including transformers, SSMs, and hybrid models. This system abstracts away differences in model loading and execution, providing a consistent interface for researchers. The system also includes verification mechanisms to benchmark forward-pass parity and generation quality against HuggingFace baselines.
TransformerLens incorporates visualization and analysis tools to aid in interpreting model internals. These include utilities for plotting attention patterns, activation heatmaps, and circuit diagrams. For example, the library provides a notation system for labeling weight matrices and activations, which is documented in diagrams created by contributors like Austin Kozlowski. These visual aids help researchers communicate findings and design experiments more effectively.
Additionally, the library has deprecated legacy components like HookedSAETransformer in favor of specialized tools such as SAELens, streamlining its codebase and improving maintainability.
The library’s documentation and tutorials serve as a gateway for new researchers entering the field. Key resources include the Main Demo, which guides users through loading models, inspecting activations, and performing interventions. Additional tutorials cover foundational topics such as induction heads, direct logit attribution, and activation patching. These materials are complemented by community-contributed examples and problem sets, such as those from the ARENA Mechanistic Interpretability Tutorials, which provide hands-on exercises and solutions.
Users can validate their experiments against HuggingFace baselines or legacy systems, ensuring that findings are grounded in consistent computational practices.