{"id":8344,"library":"ncnn","title":"NCNN Neural Network Inference Framework","description":"NCNN is a high-performance neural network inference framework optimized for mobile platforms. The `ncnn` Python library provides official Python bindings, allowing users to load and run NCNN models from Python applications. It enables efficient deep learning inference on devices with limited computational resources. The library's versioning (`1.0.YYYYMMDD`) reflects a frequent release cadence, often aligned with new features or fixes in the core C++ NCNN project.","status":"active","version":"1.0.20260114","language":"en","source_language":"en","source_url":"https://github.com/Tencent/ncnn","tags":["deep-learning","inference","mobile","neural-networks","computer-vision","edge-ai","cpp-binding"],"install":[{"cmd":"pip install ncnn","lang":"bash","label":"Install ncnn Python package"}],"dependencies":[{"reason":"Used for numerical operations and handling input/output data (e.g., converting images to ncnn.Mat).","package":"numpy"}],"imports":[{"note":"The main module for accessing NCNN functionalities like Net, Mat, etc.","symbol":"ncnn","correct":"import ncnn"},{"note":"Used to create and manage the neural network model.","symbol":"Net","correct":"from ncnn import Net"},{"note":"The primary data structure for NCNN tensors, used for inputs and outputs.","symbol":"Mat","correct":"from ncnn import Mat"}],"quickstart":{"code":"import ncnn\nimport numpy as np\nimport os\n\n# NCNN requires model files (.param and .bin)\n# For a runnable quickstart, we'll demonstrate the API flow.\n# In a real scenario, you'd replace these with actual converted model files.\n\n# Create dummy files - these are NOT functional NCNN models\n# but allow the API calls to proceed without immediate file not found errors.\n# A real NCNN model conversion would generate proper .param and .bin.\nwith open(\"dummy_model.param\", \"w\") as f:\n    f.write(\"7767517\\n0\\n\") # Minimal valid param content for an empty net\nwith open(\"dummy_model.bin\", \"wb\") as f:\n    f.write(b'') # Empty bin content\n\ntry:\n    # 1. Initialize NCNN network\n    net = ncnn.Net()\n    print(\"NCNN Net initialized.\")\n\n    # Optional: Configure options (e.g., enable Vulkan if available)\n    # net.opt.use_vulkan_compute = True \n\n    # 2. Load model structure (.param) and weights (.bin)\n    # Note: These dummy files will load but won't perform actual inference.\n    # Replace \"dummy_model.param\" and \"dummy_model.bin\" with your converted NCNN model paths.\n    ret_param = net.load_param(\"dummy_model.param\")\n    ret_bin = net.load_model(\"dummy_model.bin\")\n\n    if ret_param == 0 and ret_bin == 0:\n        print(\"Dummy NCNN model files loaded successfully.\")\n    else:\n        print(f\"Failed to load dummy model. param_ret={ret_param}, bin_ret={ret_bin}\")\n        # A non-zero return code means failure, e.g., malformed model files.\n\n    # 3. Prepare input data (e.g., from an image or NumPy array)\n    # This step is for demonstration; actual inference won't happen with dummy model.\n    dummy_input_array = np.random.rand(224, 224, 3).astype(np.float32) * 255\n    mat_in = ncnn.Mat.from_pixels(dummy_input_array, ncnn.PIXEL_RGB, 224, 224)\n    print(f\"Dummy input Mat created with shape: {mat_in.w}x{mat_in.h}x{mat_in.c}\")\n\n    # 4. Create an extractor and push input (for a real model)\n    # ex = net.create_extractor()\n    # ex.input(\"data\", mat_in) # \"data\" is a common input blob name\n\n    # 5. Run inference and extract output (for a real model)\n    # ret, mat_out = ex.extract(\"output\") # \"output\" is a common output blob name\n\n    print(\"NCNN API usage demonstrated. For real inference, replace dummy files with actual NCNN models.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up dummy files\n    if os.path.exists(\"dummy_model.param\"):\n        os.remove(\"dummy_model.param\")\n    if os.path.exists(\"dummy_model.bin\"):\n        os.remove(\"dummy_model.bin\")","lang":"python","description":"This quickstart demonstrates the basic API flow for initializing an NCNN network, loading (dummy) model files, and preparing input data using `ncnn.Mat`. It uses placeholder model files to be runnable without actual model conversion, but you would replace them with your own `.param` and `.bin` files for real inference."},"warnings":[{"fix":"Ensure CMake and a compatible C++ compiler are available in your system's PATH. E.g., `sudo apt install build-essential cmake` on Ubuntu or `brew install cmake` on macOS (after installing Xcode Command Line Tools).","message":"Installing `ncnn` via pip on certain platforms (e.g., Linux without pre-built wheels) requires a C++ compiler (like GCC/Clang) and CMake to be installed system-wide for the Python bindings to build successfully.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use the `ncnn` tools (e.g., `onnx2ncnn`, `torch2ncnn`) or third-party converters to transform your models into the `.param` and `.bin` format before attempting to load them.","message":"NCNN operates on its proprietary `.param` (network structure) and `.bin` (weights) model formats. You cannot directly load models saved from frameworks like PyTorch, TensorFlow, or ONNX. Conversion is required.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If pre-built wheels with Vulkan are not available for your platform, you may need to build `ncnn` from source, ensuring `NCNN_VULKAN=ON` during the CMake configuration step. Then set `net.opt.use_vulkan_compute = True` in your Python code.","message":"To utilize GPU acceleration with NCNN (via Vulkan), the library must be specifically compiled with Vulkan support. A standard `pip install ncnn` might provide a CPU-only build.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Inspect your model's input requirements. Use `numpy.transpose` or `ncnn.Mat.from_pixels` with correct `pixel_type` and `num_channels` arguments to match the expected layout (e.g., `ncnn.Mat.from_pixels(img, ncnn.PIXEL_BGR2RGB, img.shape[1], img.shape[0])` for HWC BGR to NCNN RGB).","message":"When converting input data (e.g., NumPy arrays) to `ncnn.Mat`, ensure the channel order (e.g., HWC vs CHW) matches what your `ncnn` model expects. Common image processing libraries often output HWC, while many NCNN models might expect CHW.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `ncnn` is installed: `pip install ncnn`.","cause":"The `ncnn` Python package is not installed in the current environment or the Python interpreter cannot find it.","error":"ModuleNotFoundError: No module named 'ncnn'"},{"fix":"Verify `ncnn` installed successfully. If building from source, ensure `libncnn.so` (or equivalent) is generated and its directory is in `LD_LIBRARY_PATH` (Linux/macOS) or `PATH` (Windows). Re-installing `ncnn` after ensuring CMake and C++ compilers are present might resolve it: `pip install --no-cache-dir --upgrade ncnn`.","cause":"The underlying C++ NCNN shared library (`libncnn.so` on Linux, `.dll` on Windows, `.dylib` on macOS) was either not built, not properly linked during Python package installation, or cannot be found by the system's dynamic linker (e.g., not in `LD_LIBRARY_PATH`). This often happens when `pip install ncnn` fails to complete the C++ compilation step or if custom builds are attempted.","error":"ImportError: libncnn.so: cannot open shared object file: No such file or directory"},{"fix":"Double-check the path to your `.param` file. Ensure the file exists and is readable. Verify that both `.param` and its corresponding `.bin` file are present and correctly generated using `ncnn`'s model conversion tools.","cause":"The `.param` file for the NCNN model is either missing, has an incorrect path, is corrupted, or is not in the correct NCNN model format.","error":"ncnn.Net: failed to load param model"},{"fix":"You must first create an instance of `ncnn.Net` before calling its methods: `net = ncnn.Net(); net.load_param('model.param')`.","cause":"Attempting to call an instance method (e.g., `load_param`, `load_model`) on the `ncnn.Net` *class* instead of an *instance* of the `ncnn.Net` class.","error":"TypeError: descriptor 'load_param' for 'ncnn.Net' objects doesn't apply to a 'str' object"}]}