Install & Compatibility
Where this runs
tested against v1.0.20260526 · 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.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.8s · import 0.010s · 301MB
303MB installed
● package 303MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ncnn
✓ import ncnn
The main module for accessing NCNN functionalities like Net, Mat, etc.
Net
✓ from ncnn import Net
Used to create and manage the neural network model.
Mat
✓ from ncnn import Mat
The primary data structure for NCNN tensors, used for inputs and outputs.
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.
import ncnn
import numpy as np
import os
# NCNN requires model files (.param and .bin)
# For a runnable quickstart, we'll demonstrate the API flow.
# In a real scenario, you'd replace these with actual converted model files.
# Create dummy files - these are NOT functional NCNN models
# but allow the API calls to proceed without immediate file not found errors.
# A real NCNN model conversion would generate proper .param and .bin.
with open("dummy_model.param", "w") as f:
f.write("7767517\n0\n") # Minimal valid param content for an empty net
with open("dummy_model.bin", "wb") as f:
f.write(b'') # Empty bin content
try:
# 1. Initialize NCNN network
net = ncnn.Net()
print("NCNN Net initialized.")
# Optional: Configure options (e.g., enable Vulkan if available)
# net.opt.use_vulkan_compute = True
# 2. Load model structure (.param) and weights (.bin)
# Note: These dummy files will load but won't perform actual inference.
# Replace "dummy_model.param" and "dummy_model.bin" with your converted NCNN model paths.
ret_param = net.load_param("dummy_model.param")
ret_bin = net.load_model("dummy_model.bin")
if ret_param == 0 and ret_bin == 0:
print("Dummy NCNN model files loaded successfully.")
else:
print(f"Failed to load dummy model. param_ret={ret_param}, bin_ret={ret_bin}")
# A non-zero return code means failure, e.g., malformed model files.
# 3. Prepare input data (e.g., from an image or NumPy array)
# This step is for demonstration; actual inference won't happen with dummy model.
dummy_input_array = np.random.rand(224, 224, 3).astype(np.float32) * 255
mat_in = ncnn.Mat.from_pixels(dummy_input_array, ncnn.PIXEL_RGB, 224, 224)
print(f"Dummy input Mat created with shape: {mat_in.w}x{mat_in.h}x{mat_in.c}")
# 4. Create an extractor and push input (for a real model)
# ex = net.create_extractor()
# ex.input("data", mat_in) # "data" is a common input blob name
# 5. Run inference and extract output (for a real model)
# ret, mat_out = ex.extract("output") # "output" is a common output blob name
print("NCNN API usage demonstrated. For real inference, replace dummy files with actual NCNN models.")
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Clean up dummy files
if os.path.exists("dummy_model.param"):
os.remove("dummy_model.param")
if os.path.exists("dummy_model.bin"):
os.remove("dummy_model.bin")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ncnn'
The `ncnn` Python package is not installed in the current environment or the Python interpreter cannot find it.
fixEnsure `ncnn` is installed: `pip install ncnn`.
ImportError: libncnn.so: cannot open shared object file: No such file or directory
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.
fixVerify `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`.
ncnn.Net: failed to load param model
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.
fixDouble-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.
TypeError: descriptor 'load_param' for 'ncnn.Net' objects doesn't apply to a 'str' object
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.
fixYou must first create an instance of `ncnn.Net` before calling its methods: `net = ncnn.Net(); net.load_param('model.param')`. Upgrade
Version history
1.0.20260526latest on PyPI · released May 26, 2026
Audit
Dependencies
numpyrequiredUsed for numerical operations and handling input/output data (e.g., converting images to ncnn.Mat).