Implementation:Tencent Ncnn Pnnx Export

Knowledge Sources	ncnn PNNX README
Domains	Model_Conversion, Model_Deployment
Last Updated	2026-02-09 00:00 GMT

Overview

External tool for converting TorchScript models to ncnn format via the PNNX converter, provided as both a Python API and CLI tool.

Description

pnnx is available as a pip-installable Python package and as a standalone CLI tool built from the ncnn source tree (tools/pnnx/). The Python API (pnnx.export) takes a PyTorch model and input tensor directly, while the CLI takes a TorchScript .pt file with shape specifications.

PNNX outputs multiple files: model.ncnn.param (network structure), model.ncnn.bin (weights), model_pnnx.py (re-exportable Python), and model.pnnx.param/model.pnnx.bin (PNNX IR for debugging).

Usage

Use after exporting a PyTorch model to TorchScript. Install via pip install pnnx or build from ncnn source. Pass the TorchScript file and input shape specification.

Code Reference

Source Location

• Repository: ncnn
• File: tools/pnnx/README.md (documentation, 751 lines), tools/pnnx/CMakeLists.txt (build config)

Signature

# Python API
import pnnx

pnnx.export(
    model,                    # nn.Module — the PyTorch model
    ptpath,                   # str — base name for output files
    inputs,                   # Tensor or tuple — example input(s)
    inputs2=None,             # optional second shape for dynamic
    device="cpu",             # "cpu" or "gpu"
    optlevel=2,               # optimization level (0-2)
    fp16=False,               # enable fp16 weight storage
    customop=None,            # custom op module paths
    moduleop=None             # module-level op paths
)

# CLI usage
pnnx model.pt \
    inputshape=[1,3,224,224] \
    inputshape2=[1,3,320,320] \
    device=cpu \
    optlevel=2

Import

import pnnx
# pip install pnnx

I/O Contract

Inputs

Name	Type	Required	Description
model / .pt file	nn.Module or path	Yes	TorchScript model or PyTorch module
inputshape	str or Tensor	Yes	Input tensor shape (e.g., [1,3,224,224])
inputshape2	str or Tensor	No	Second shape for dynamic input support
device	str	No	"cpu" or "gpu" (default: "cpu")
optlevel	int	No	Optimization level 0-2 (default: 2)

Outputs

Name	Type	Description
model.ncnn.param	File	ncnn network structure (plain text)
model.ncnn.bin	File	ncnn network weights (binary)
model_pnnx.py	File	Re-exportable Python module
model.pnnx.param/bin	File	PNNX IR (for debugging)

Usage Examples

Python API

import torch
import torchvision
import pnnx

model = torchvision.models.resnet18(pretrained=True)
model.eval()

x = torch.randn(1, 3, 224, 224)
pnnx.export(model, "resnet18", x)
# Produces: resnet18.ncnn.param, resnet18.ncnn.bin

CLI with Dynamic Shapes

# Convert with two input shapes for dynamic inference
pnnx yolov8n.torchscript \
    inputshape=[1,3,640,640] \
    inputshape2=[1,3,320,320]

# Output: yolov8n.torchscript.ncnn.param, yolov8n.torchscript.ncnn.bin

Related Pages

Implements Principle

• Principle:Tencent_Ncnn_PNNX_Model_Conversion

Requires Environment

• Environment:Tencent_Ncnn_PyTorch_Environment