{"id":8326,"library":"mnn","title":"MNN Python Binding","description":"MNN (Mobile Neural Network) is a blazing-fast, lightweight deep learning inference engine developed by Alibaba. It supports inference and training of deep learning models, offering high performance on various devices, including mobile and embedded systems. The Python package `mnn` provides APIs for inference, training, image processing, and numerical computation, allowing ML engineers to use MNN without dipping their toes in C++ code. It is currently at version 3.5.0 and maintains an active development and release cadence.","status":"active","version":"3.5.0","language":"en","source_language":"en","source_url":"https://github.com/alibaba/MNN","tags":["deep-learning","inference","machine-learning","mobile","edge-ai","onnx","tensorflow","caffe","computer-vision"],"install":[{"cmd":"pip install MNN","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for numerical operations, especially with MNN.numpy.","package":"numpy"}],"imports":[{"symbol":"MNN","correct":"import MNN"},{"symbol":"MNN.nn","correct":"import MNN.nn as nn"},{"symbol":"MNN.cv","correct":"import MNN.cv as cv"},{"symbol":"MNN.numpy","correct":"import MNN.numpy as np"},{"note":"Direct `MNN.expr` is the current pattern.","wrong":"import MNN.core.expr","symbol":"MNN.expr","correct":"import MNN.expr as expr"},{"note":"The Session API (which uses Interpreter) is deprecated; prefer Module API.","wrong":"from MNN.Interpreter import Interpreter","symbol":"MNN.Interpreter","correct":"from MNN import Interpreter"}],"quickstart":{"code":"import MNN.nn as nn\nimport MNN.cv as cv\nimport MNN.numpy as np\nimport MNN.expr as expr\nimport os\n\n# Assuming 'mobilenet_v1.mnn' and 'cat.jpg' exist in the current directory\n# In a real scenario, you'd download these or replace with your model/image.\n# For demonstration, we'll create dummy files if they don't exist.\n\n# Create a dummy MNN model file if it doesn't exist (for runnable example)\nif not os.path.exists('mobilenet_v1.mnn'):\n    print(\"Creating dummy mobilenet_v1.mnn for quickstart. This won't run a real model.\")\n    with open('mobilenet_v1.mnn', 'w') as f:\n        f.write('dummy_model_content')\n\n# Create a dummy image file if it doesn't exist (for runnable example)\nif not os.path.exists('cat.jpg'):\n    print(\"Creating dummy cat.jpg for quickstart. This won't process a real image.\")\n    # Using PIL to create a simple dummy image\n    try:\n        from PIL import Image\n        img = Image.new('RGB', (224, 224), color = 'red')\n        img.save('cat.jpg')\n    except ImportError:\n        print(\"Pillow not installed. Skipping dummy image creation.\")\n        print(\"Please install Pillow (pip install Pillow) or provide a 'cat.jpg'.\")\n\n# Configure runtime (e.g., backend, threads, precision)\n# Backend 0 typically refers to CPU. 'low' precision might enable FP16 if hardware supports.\nconfig = {\n    'precision': 'low', \n    'backend': 0,      \n    'numThread': 4     \n}\nruntime_manager = nn.create_runtime_manager((config,))\n\n# Load model using the Module API\n# 'data' and 'prob' are example input/output names, adapt to your model\ntry:\n    net = nn.load_module_from_file('mobilenet_v1.mnn', ['data'], ['prob'], runtime_manager=runtime_manager)\nexcept Exception as e:\n    print(f\"Could not load dummy model: {e}. Please ensure 'mobilenet_v1.mnn' is a valid MNN model.\")\n    exit()\n\n# Read and preprocess image using MNN.cv and MNN.numpy\n# Mean and norm values are typical for MobileNet preprocessing\nimage = cv.imread('cat.jpg')\nif image is not None:\n    image = cv.resize(image, (224, 224), mean=[103.94, 116.78, 123.68], norm=[0.017, 0.017, 0.017])\n    input_var = np.expand_dims(image, 0) # Add batch dimension (HWC to NHWC)\n    input_var = expr.convert(input_var, expr.NC4HW4) # NHWC to NC4HW4 for MNN\n\n    # Perform inference\n    output_var = net.forward(input_var)\n\n    # Post-process output\n    output_var = expr.convert(output_var, expr.NHWC) # NC4HW4 to NHWC\n    # For a real classification model, you would interpret 'output_var' here\n    print(f\"Inference output shape: {output_var.shape}\")\n    # Example: print top-1 class if it's a classification model\n    # print(f\"Output belongs to class: {np.argmax(output_var)}\")\nelse:\n    print(\"Could not read image. Ensure 'cat.jpg' exists and is a valid image.\")\n","lang":"python","description":"This quickstart demonstrates loading an MNN model, preprocessing an image using `MNN.cv` and `MNN.numpy`, performing inference with the `Module API`, and post-processing the output. Replace `mobilenet_v1.mnn` and `cat.jpg` with your actual model and input data. The code includes creation of dummy files for runnable demonstration purposes if actual files are not present."},"warnings":[{"fix":"Rewrite code to use `MNN.nn.load_module_from_file` to load models and interact with `_Module` objects (or custom `nn.Module` subclasses) and their `forward` method.","message":"The MNN Python Session API (`MNN.Interpreter`, `MNN.Session`) is deprecated. Users should migrate to the Module API (`MNN.nn.Module`, `MNN.nn.load_module_from_file`) for all inference and training tasks.","severity":"deprecated","affected_versions":"All versions from 2.0.0 onwards, explicitly deprecated in newer docs."},{"fix":"Minimize complex or repetitive operations using `MNN.cv` and `MNN.numpy` in performance-critical loops. Optimize data flow and batching.","message":"MNN.cv and MNN.numpy, while lightweight, involve graph construction, operation, and destruction which can become a performance bottleneck on mobile devices if overused. Keep pre/post-processing logic simple.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Ensure that if `--saveExternalData` was used during conversion, the corresponding `.mnn.weight` file is present alongside the `.mnn` model, and specify its path when initializing the `RuntimeManager` or loading the module.","message":"When converting models using `MNNConvert` with the `--saveExternalData` flag, a separate weight file (`.mnn.weight`) is generated. This external weight file must be explicitly specified when loading the model via the Python Module API using `RuntimeManager::setExternalFile` for correct operation.","severity":"gotcha","affected_versions":"MNN 2.3.0 and later."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install MNN`","cause":"The MNN Python package is not installed in the current Python environment or the environment where the script is being run.","error":"ModuleNotFoundError: No module named 'MNN'"},{"fix":"Verify the correct import path and module structure. Most new APIs reside in `MNN.nn`, `MNN.cv`, `MNN.numpy`, or `MNN.expr`. For instance, `MNN.Interpreter` is deprecated; use `MNN.nn`.","cause":"Attempting to access a function or submodule that does not exist directly under the `MNN` top-level module, or using a deprecated API. For example, some functionalities are under `MNN.nn`, `MNN.cv`, `MNN.numpy`, or `MNN.expr`.","error":"AttributeError: module 'MNN' has no attribute 'some_function'"},{"fix":"Ensure `Var` objects are properly converted to NumPy arrays (e.g., `output_var.read()`) or processed with `MNN.numpy` operations before attempting direct indexing or iteration.","cause":"This often happens when model outputs or intermediate tensors are treated as Python lists or arrays prematurely. MNN operations often return `MNN.expr.Var` objects that need further processing (e.g., conversion or explicit numpy operations) before direct Python list-like access.","error":"TypeError: 'float' object is not subscriptable"},{"fix":"Double-check the file path. Ensure the model and image files are in the expected location relative to your script, or provide an absolute path. Use `os.path.exists()` for debugging.","cause":"The specified MNN model file (e.g., `mobilenet_v1.mnn`) or image file (`cat.jpg`) cannot be found at the given path. This can be due to an incorrect file path, the file not existing, or incorrect working directory.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'your_model.mnn'"}]}