Registry / ai-ml / transformer-engine

transformer-engine

JSON →
library2.16.0pypypiunverified

Transformer Engine (TE) is a library developed by NVIDIA for accelerating Transformer models on NVIDIA GPUs. It enables the use of 8-bit floating point (FP8) and 4-bit floating point (NVFP4) precision on architectures like Hopper, Ada, and Blackwell, significantly improving performance and reducing memory utilization during both training and inference. TE provides highly optimized building blocks for common Transformer architectures and an automatic mixed-precision-like API that integrates seamlessly with PyTorch and JAX. The library has frequent releases, often aligned with updates to NVIDIA's deep learning software stack.

pip install transformer-engine
INSTALL
IMPORT
SIG · TRANSFORMER-ENGINE
T
transformer-engine
ai-mlpythonv2.16.0
Install
5.8s avg
Import
—
Disk
118MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v2.16.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.000s · 25.3MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 5.8s · import 0.000s · 26MB
118MB installed
● package 118MB
Code
Verified usage

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

Linear
✓ from transformer_engine.pytorch import Linear
✗ from transformer_engine.pytorch import Linear

This quickstart demonstrates how to initialize `transformer_engine.pytorch.Linear` and `transformer_engine.pytorch.TransformerLayer` modules and perform a forward pass using `fp8_autocast` for 8-bit floating point precision. It highlights the use of `torch.bfloat16` as a base precision and includes a basic FP8 recipe configuration. Ensure you have an NVIDIA GPU with CUDA installed.

import torch import transformer_engine.pytorch as te from transformer_engine.pytorch import fp8_autocast from transformer_engine.common import recipe # Check for GPU availability if not torch.cuda.is_available(): print("CUDA not available. Transformer Engine requires an NVIDIA GPU.") exit() # Define model dimensions in_features = 1024 out_features = 2048 batch_size = 16 sequence_length = 128 # Create a sample input tensor input_tensor = torch.randn(batch_size, sequence_length, in_features, device='cuda', dtype=torch.bfloat16) # Initialize a Transformer Engine Linear layer te_linear = te.Linear(in_features, out_features, bias=True, dtype=torch.bfloat16).cuda() # Define an FP8 recipe (optional, for fine-grained control) fp8_recipe = recipe.DelayedScaling(margin=0, interval=1, fp8_format=recipe.Format.E4M3, amax_history_len=1024) print(f"Input tensor shape: {input_tensor.shape}, dtype: {input_tensor.dtype}") # Perform a forward pass with FP8 autocasting with fp8_autocast(enabled=True, fp8_recipe=fp8_recipe): output_tensor = te_linear(input_tensor) print(f"Output tensor shape (with FP8 autocast): {output_tensor.shape}, dtype: {output_tensor.dtype}") # Example of using a TransformerLayer num_heads = 16 hidden_size = in_features ffn_hidden_size = out_features # TransformerLayer requires a specific config te_transformer_layer = te.TransformerLayer( hidden_size=hidden_size, ffn_hidden_size=ffn_hidden_size, num_attention_heads=num_heads, fuse_qkv_params=True, # Common optimization params_dtype=torch.bfloat16 ).cuda() with fp8_autocast(enabled=True, fp8_recipe=fp8_recipe): # TransformerLayer typically takes (sequence_length, batch_size, hidden_size) # Permute input_tensor for TransformerLayer if needed output_transformer_layer = te_transformer_layer(input_tensor.transpose(0, 1)) print(f"Output from TransformerLayer (with FP8 autocast): {output_transformer_layer.shape}, dtype: {output_transformer_layer.dtype}")
Debug
Known issues
breakingTransformer Engine v2.13 removed deprecated packed fused attention C APIs (nvte_fused_attn_{fwd,bwd}_{qkvpacked,kvpacked}). Users must migrate to the non-packed API variants.
fix
Update C++ code or custom integrations to use the non-packed fused attention C APIs. Refer to the v2.13 release notes for specific migration details.
affects: >=2.13.0
breakingIn Transformer Engine v1.7, the padding mask definition for PyTorch changed. `True` now means masking out the corresponding position, while `False` means including it. This unifies mask definitions across supported frameworks.
fix
Review and invert boolean logic for padding masks in PyTorch code if it was written for versions prior to v1.7. `True` now *excludes* positions.
affects: >=1.7.0
breakingTransformer Engine v2.2 introduced multiple breaking changes in the `InferenceParams` class, requiring new arguments (`num_heads_kv`, `head_dim_k`, `dtype`) during initialization and requiring a call to `pre_step` to update the state. The `swap_key_value_dict` method was also removed.
fix
Update `InferenceParams` initialization and usage according to the v2.2 release notes, ensuring all new required arguments are provided and `pre_step` is called. Replace `swap_key_value_dict` usage with the new automatic reordering in `step`.
affects: >=2.2.0
deprecatedTransformer Engine v2.3 deprecated CPU offloading weight tensors. Support for installations *without* the `--no-build-isolation` flag will also be removed in a future release.
fix
Avoid CPU offloading for weight tensors. When installing, always use `pip install transformer-engine --no-build-isolation` to prepare for future releases.
affects: >=2.3.0
gotchaFP8 execution might be slower than FP16/BF16 for small models or batch sizes due to overheads from FP8 casts and increased CPU overhead from `te.Linear`'s additional logic compared to `torch.nn.Linear`.
fix
For optimal FP8 performance, use Transformer Engine with larger models and batch sizes where the computational benefits outweigh casting and CPU overheads. Ensure GPU compute can cover CPU overheads by avoiding frequent GPU synchronization.
affects: All
gotcha`ModuleNotFoundError` may occur if `transformer-engine` is installed via PyPI in an environment with CUDA version less than 12.8.
fix
Ensure your CUDA installation is 12.8 or newer. If not, install `transformer-engine` from source as a temporary workaround until this issue is fully addressed in later releases.
affects: <2.3.0
gotchaFlashAttention v2.1 and later changed the behavior of the causal mask when performing cross-attention. To maintain consistent behavior across Transformer Engine versions and backends, FlashAttention is *disabled* for this specific use case (cross-attention with causal masking) when v2.1+ is installed.
fix
Be aware that FlashAttention may not be used for cross-attention with causal masking. If this specific scenario is critical for performance, consider alternative attention implementations or inspect your FlashAttention version.
affects: >=1.2.1
Upgrade
Version history
2.16.0latest on PyPI · released Jun 9, 2026
Audit
Dependencies
torchoptionalPrimary deep learning framework integration for PyTorch API.
jaxoptionalDeep learning framework integration for JAX API.
cudarequiredRequires NVIDIA CUDA Toolkit for GPU acceleration.
flash-attnoptionalOptional dependency for FlashAttention integration to further improve performance.
Agent activity
47 hits · last 30 days
node
41
OpenAI (training)
1
Resources
transformer-engine — pip install transformer-engine · libregistry