{"id":5324,"library":"mmengine","title":"MMEngine","description":"MMEngine is the foundational training engine for OpenMMLab projects, providing a comprehensive and flexible framework for deep learning training, evaluation, and deployment. It offers utilities for configuration management, logging, hooks, runners, and visualization. The current stable version is 0.10.7, with frequent patch and minor releases and active development towards 0.11.0.","status":"active","version":"0.10.7","language":"python","source_language":"en","source_url":"https://github.com/open-mmlab/mmengine","tags":["machine learning","deep learning","training framework","computer vision","openmmlab","pytorch"],"install":[{"cmd":"pip install mmengine","lang":"bash","label":"Stable release"}],"dependencies":[{"reason":"MMEngine is primarily used for PyTorch-based deep learning tasks. While not a strict core dependency, it's almost always required for practical use.","package":"torch","optional":true},{"reason":"Used for image processing utilities. Starting from v0.11.0, this becomes the default OpenCV variant for MMEngine.","package":"opencv-python-headless","optional":true}],"imports":[{"symbol":"Config","correct":"from mmengine.config import Config"},{"note":"For OpenMMLab V1.0+, Runner functionality migrated from MMCV to MMEngine.","wrong":"from mmcv.runner import Runner","symbol":"Runner","correct":"from mmengine.runner import Runner"},{"symbol":"LoggerHook","correct":"from mmengine.hooks import LoggerHook"},{"symbol":"Visualizer","correct":"from mmengine.visualization import Visualizer"},{"note":"Registry for datasets, similar patterns for MODELS, OPTIMIZERS, etc.","symbol":"DATASETS","correct":"from mmengine.registry import DATASETS"}],"quickstart":{"code":"from mmengine.config import Config\n\n# Define configuration using a dictionary\ncfg_dict = dict(\n    model=dict(type='MyCustomModel', num_classes=10, init_cfg=None),\n    dataloader=dict(batch_size=32, num_workers=4),\n    optimizer=dict(type='Adam', lr=0.001)\n)\n\n# Create a Config object\ncfg = Config(cfg_dict)\n\n# Access configuration parameters\nprint(f\"Model type: {cfg.model.type}\")\nprint(f\"Optimizer learning rate: {cfg.optimizer.lr}\")\n\n# You can also load from a file:\n# cfg = Config.fromfile('path/to/your_config.py')\n","lang":"python","description":"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."},"warnings":[{"fix":"Refer to the MMEngine migration guides and the documentation for specific OpenMMLab projects (e.g., MMDetection V3.x, MMSegmentation V1.x) for updated API usage.","message":"Major 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.","severity":"breaking","affected_versions":"Prior to OpenMMLab V1.0 frameworks (e.g., before MMEngine v0.1.0) to current."},{"fix":"Familiarize yourself with the MMEngine Config tutorial. Ensure components are correctly registered and paths for inherited configs are resolved properly.","message":"MMEngine'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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install necessary optional dependencies explicitly (e.g., `pip install 'mmengine[tensorboard]'`). Check the MMEngine installation guide for specific extras.","message":"Many 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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If GUI features are needed, explicitly install `opencv-python` alongside `mmengine` and ensure it takes precedence if multiple `opencv` packages are present.","message":"Starting 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.","severity":"gotcha","affected_versions":"v0.11.0 and later (currently in RC)"},{"fix":"Upgrade MMEngine to v0.11.0rc0 or later if using Python 3.12, or use a Python version officially supported by your MMEngine version.","message":"Versions prior to v0.11.0rc0 may encounter bugs related to config parsing when running on Python 3.12.","severity":"gotcha","affected_versions":"Prior to v0.11.0rc0"}],"env_vars":null,"search_vec":"'0.10.7':40 '0.11.0':51 'activ':48 'comprehens':13 'comput':58 'configur':28 'current':36 'deep':18,54 'deploy':23 'develop':49 'engin':7 'evalu':21 'flexibl':15 'foundat':5 'framework':16,57 'frequent':42 'hook':31 'learn':19,53,55 'log':30 'machin':52 'manag':29 'minor':45 'mmengin':1,2 'offer':25 'openmmlab':9,60 'patch':43 'project':10 'provid':11 'pytorch':61 'releas':46 'runner':32 'stabl':37 'toward':50 'train':6,20,56 'util':26 'version':38 'vision':59 'visual':34","created_at":"2026-04-14T01:28:57.916709+00:00","updated_at":"2026-04-16T16:37:26.345061+00:00","problems":[{"fix":"Ensure 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.","cause":"The 'mmengine' package is either not installed in the current Python environment, or the environment where it is installed is not activated.","error":"ModuleNotFoundError: No module named 'mmengine'"},{"fix":"Review 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.","cause":"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.","error":"AttributeError: 'ConfigDict' object has no attribute 'model'"},{"fix":"Ensure 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.","cause":"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.","error":"KeyError: 'Recognizer2D is not in the model registry. Please check whether the value of `Recognizer2D` is correct or it was registered as expected.'"},{"fix":"When 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.","cause":"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.","error":"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."},{"fix":"When 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`.","cause":"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.","error":"ValueError: train_dataloader, train_cfg, and optim_wrapper should be either all None or not None"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.10.7","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/open-mmlab/mmengine","docs":null,"changelog":null,"pypi":"https://pypi.org/project/mmengine/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}