Install & Compatibility
Where this runs
tested against v0.10.7 · 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
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 11.4s · import 1.110s · 379MB
387MB installed
● package 387MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Config
✓ from mmengine.config import Config
Runner
✓ from mmengine.runner import Runner
✗ from mmcv.runner import Runner
For OpenMMLab V1.0+, Runner functionality migrated from MMCV to MMEngine.
LoggerHook
✓ from mmengine.hooks import LoggerHook
Visualizer
✓ from mmengine.visualization import Visualizer
DATASETS
✓ from mmengine.registry import DATASETS
Registry for datasets, similar patterns for MODELS, OPTIMIZERS, etc.
This quickstart demonstrates how to define and use a configuration object in MMEngine. The `Config` class is central to managing experiment settings, model architectures, and training parameters, often loaded from Python files.
from mmengine.config import Config
# Define configuration using a dictionary
cfg_dict = dict(
model=dict(type='MyCustomModel', num_classes=10, init_cfg=None),
dataloader=dict(batch_size=32, num_workers=4),
optimizer=dict(type='Adam', lr=0.001)
)
# Create a Config object
cfg = Config(cfg_dict)
# Access configuration parameters
print(f"Model type: {cfg.model.type}")
print(f"Optimizer learning rate: {cfg.optimizer.lr}")
# You can also load from a file:
# cfg = Config.fromfile('path/to/your_config.py')
Debug
Known issues
breakingMajor API refactor for OpenMMLab V1.0 projects. If migrating from older OpenMMLab frameworks (e.g., using `mmcv.runner`), significant code changes are required as MMEngine unifies the core engine components.fixRefer to the MMEngine migration guides and the documentation for specific OpenMMLab projects (e.g., MMDetection V3.x, MMSegmentation V1.x) for updated API usage.
affects: Prior to OpenMMLab V1.0 frameworks (e.g., before MMEngine v0.1.0) to current.
gotchaMMEngine's Config system uses Python files (`.py`) for configurations, allowing for complex logic and inheritance. This differs from older YAML/JSON configurations. Misunderstanding the inheritance mechanism or how `register_module` works can lead to errors.fixFamiliarize yourself with the MMEngine Config tutorial. Ensure components are correctly registered and paths for inherited configs are resolved properly.
affects: All versions
gotchaMany advanced features, optimizers, and visualization backends (e.g., MLflow, TensorBoard, specific deepspeed optimizers) are optional dependencies. Attempting to use them without prior installation will result in `ImportError`.fixInstall necessary optional dependencies explicitly (e.g., `pip install 'mmengine[tensorboard]'`). Check the MMEngine installation guide for specific extras.
affects: All versions
gotchaStarting from v0.11.0, MMEngine will default to using `opencv-python-headless` for image processing. If your workflow relies on `opencv-python` with GUI functionalities, ensure it's explicitly installed and managed.fixIf GUI features are needed, explicitly install `opencv-python` alongside `mmengine` and ensure it takes precedence if multiple `opencv` packages are present.
affects: v0.11.0 and later (currently in RC)
gotchaVersions prior to v0.11.0rc0 may encounter bugs related to config parsing when running on Python 3.12.fixUpgrade MMEngine to v0.11.0rc0 or later if using Python 3.12, or use a Python version officially supported by your MMEngine version.
affects: Prior to v0.11.0rc0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mmengine'
The 'mmengine' package is either not installed in the current Python environment, or the environment where it is installed is not activated.
fixEnsure you have activated the correct Python environment, then install mmengine using pip: `pip install mmengine` or `pip install -U openmim` followed by `mim install mmengine` if using OpenMMLab's package manager.
AttributeError: 'ConfigDict' object has no attribute 'model'
This error typically occurs when trying to access a configuration parameter (like 'model', 'test_pipeline', or 'data') that is not defined or has a different structure in your configuration file (ConfigDict object). It often happens due to typos or outdated config file formats after library updates.
fixReview your configuration file to ensure the attribute path (`cfg.model`, `cfg.test_pipeline`, etc.) matches the actual structure of your config. Refer to the latest mmengine documentation or example configurations for the expected structure.
KeyError: 'Recognizer2D is not in the model registry. Please check whether the value of `Recognizer2D` is correct or it was registered as expected.'
MMEngine uses a registry system to manage and build modules. This error means that the class 'Recognizer2D' (or any other specified module) was not found in the expected registry, often because the module was not properly registered or its corresponding file was not imported.
fixEnsure that the module containing 'Recognizer2D' is correctly imported (e.g., by adding `custom_imports` in your config or explicitly importing the module in your code) and that 'Recognizer2D' itself is decorated with `@MODELS.register_module()` (or the appropriate registry) to register it. Also, check for typos in the class name.
RuntimeError: Expected to have finished reduction in the prior iteration before starting a new one. This error indicates that your module has parameters that were not used in producing loss.
This error occurs during distributed training (DDP) when some model parameters are involved in the forward pass but do not contribute to the loss calculation. PyTorch's DDP expects all parameters to be used in loss computation for proper gradient reduction.
fixWhen initializing `torch.nn.parallel.DistributedDataParallel`, set `find_unused_parameters=True`. Additionally, ensure that all outputs of your model's `forward` function participate in calculating the loss.
ValueError: train_dataloader, train_cfg, and optim_wrapper should be either all None or not None
This error from `mmengine.runner.Runner` indicates an inconsistency in the provided training configurations. If you intend to train, all three parameters (`train_dataloader`, `train_cfg`, and `optim_wrapper`) must be provided, or all must be None if you are not performing training.
fixWhen creating or configuring the `Runner`, ensure that if `train_dataloader` is set, then `train_cfg` (the training loop configuration) and `optim_wrapper` (optimizer wrapper configuration) are also properly defined, and vice-versa. If no training is intended, set all three to `None`.
Upgrade
Version history
0.10.7latest on PyPI · released Mar 4, 2025
Audit
Dependencies
torchoptionalMMEngine is primarily used for PyTorch-based deep learning tasks. While not a strict core dependency, it's almost always required for practical use.
opencv-python-headlessoptionalUsed for image processing utilities. Starting from v0.11.0, this becomes the default OpenCV variant for MMEngine.