Important
Megatron-Bridge is the official NVIDIA maintained version, we will migrate to Megatron-Bridge soon.
MBridge: Bridge Megatron-Core to Hugging Face/Reinforcement Learning
MBridge provides a seamless bridge between Hugging Face models and Megatron-Core's optimized implementation for efficient distributed training and inference. It also offers necessary tools and processes for integrating Reinforcement Learning (RL) with Megatron.
MBridge is a prototype project, the idea has been adopted as Megatron-Bridge. For more advanced features such as training loop, mixed precision(FP8, BF16, FP4 etc.), PEFT, please refer to Megatron-Bridge.
202508 Update
- Support loading FP8 HF weights directly when training DeepSeekV3 models with bfloat16, without saving extra Megatron-Core format weights (MTP included, based on the dequantization kernel provided by DeepSeek) see example/4
Overview
MBridge allows you to convert popular Hugging Face models to Megatron-Core format, enabling you to leverage advanced parallelism strategies for large-scale training and inference. The library supports various model architectures and simplifies the process of transitioning between these frameworks. For Reinforcement Learning workflows, MBridge provides interfaces and tools needed to connect RL algorithms with Megatron-optimized models.
Feature Highlights
- Comprehensive Model Support: Support for various model architectures including MoE models (Mixture of Experts)
- Online Weight Import: Online loading HF weights with various parallelism strategies, auto shard the weights, no need to save extra Megatron-Core format weights
- Online Weight Export: Online exporting weights to HF format for inference engines, with support for TP/PP/CP/VPP/EP/ETP parallelism strategies
- Memory Friendly: Use per-tensor strategies, minimize the memory peak when loading/exporting HF format weights.
- Simple API: Intuitive interfaces for model conversion and weight management
- Support Transformer Engine: Use the powerful Transformer Engine to accelerate Megatron-Core models for better performance (use_te=False is not supported now)
Installation
pip install mbridge
Quick Start
from megatron.core import parallel_state as mpu
from mbridge import AutoBridge
# Initialize distributed environment
mpu.initialize_model_parallel(
tensor_model_parallel_size=tp,
pipeline_model_parallel_size=pp,
virtual_pipeline_model_parallel_size=vpp,
context_parallel_size=cp,
expert_model_parallel_size=ep,
)
# Load a model from Hugging Face
HF_MODEL_PATH = "/path/to/Qwen/Qwen2.5-7B-Instruct"
# or llama model
HF_MODEL_PATH = "/path/to/llama/llama3-8b-instruct"
bridge = AutoBridge.from_pretrained(HF_MODEL_PATH)
# Get a Megatron-Core model and load weights from Hugging Face
model = bridge.get_model(weight_path=HF_MODEL_PATH)
# Export weights back to Hugging Face format for inference engine
for key, weight in bridge.export_weights(model):
# Process or save the exported weights
print(f"Exported: {key}")
# save model with HF format
bridge.save_weights(model, "path/to/save/model", memory_efficient=False) # set memory_efficient=True if the model is vary large
Supported Models
Currently supported models:
- Qwen2
- Qwen2-MoE
- Qwen3
- Qwen3-MoE
- LLaMA
- DeepseekV3
- Mixtral
- Qwen2.5-VL
- Mimo
Examples
The example directory contains scripts demonstrating common use cases:
0.load_model_and_generate_single_gpu.py: Loading a model and generating text on a single GPU1.load_model_and_export_single_gpu.py: Loading a model and exporting weights on a single GPU2.load_model_and_export_multiple_gpus.py: Loading a model and exporting weights using multiple GPUs with TP/PP/CP/VPP parallelism
Post Model Creation Callbacks
MBridge provides a set of post model creation callbacks to customize the model after it is created.
make_value_model: Add a value model to the modelfreeze_moe_router: Freeze the router of the model
from mbridge.utils.post_creation_callbacks import make_value_model, freeze_moe_router
bridge = AutoBridge.from_pretrained(HF_MODEL_PATH)
model = bridge.get_model(weight_path=HF_MODEL_PATH, post_model_creation_callbacks=[make_value_model, freeze_moe_router])
Development Roadmap
MBridge will continue to maintain support for popular models, but will not develop more advanced features. See Megatron-Bridge for more advanced features.
Acknowledgements
- veRL has adopted MBridge as a connector to Megatron-Core.
- slime has adopted MBridge as Megatron-Core checkpoint converter.
- Nemo-RL has adopted Megatron-Bridge as Megatron-Core connector.
- Community contributions: Special Thanks to @Thaurun @liuzhenhai93 @jeffhong1997 from wechat team for contributing lots of VLM models support.
License
Copyright (c) 2025, NVIDIA CORPORATION. All rights reserved.
Metadata
Release files for mbridge 0.15.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mbridge-0.15.1.tar.gz | 99.3 kB | With provenance | Details for mbridge-0.15.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mbridge-0.15.1-py3-none-any.whl | Python 3 | none | any | Details for mbridge-0.15.1-py3-none-any.whl |
Total release size: 221.5 kB
Release files / mbridge-0.15.1.tar.gz
| Download URL | mbridge-0.15.1.tar.gz |
|---|---|
| Size | 99.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
26028dbe7dc9193c6c6b3de56e82691c9a484f46ded1ed18a41f2747a08e8104
|
|
BLAKE2b-256 checksum How to use checksums |
653f04534fb2b4ddf6b293ee41f839de8ae6542ef2dc1b32c7d25a4b5b18c1bb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2025.
Transparency logRelease files / mbridge-0.15.1-py3-none-any.whl
| Download URL | mbridge-0.15.1-py3-none-any.whl |
|---|---|
| Size | 122.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5c7c007c2eb13bb2d0ce9bd6b313537024d0a7fad52179ff367635eafe5cd4cd
|
|
BLAKE2b-256 checksum How to use checksums |
51dc8208746f41ff08d0b6eb8c261569d57af97648ee0d1631ea273e68c627dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2025.
Transparency logSecurity for mbridge 0.15.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mbridge-0.15.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2025.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.