Registry / ai-ml / pnnx
library20260526pypypi✓ verified 84d ago

PNNX (PyTorch to NCNN eXporter) is a Python command-line tool designed for PyTorch model interoperability, primarily converting PyTorch models into the NCNN deep learning inference framework format, or ONNX. It is maintained by Tencent and is part of the larger NCNN project. The current PyPI version is 20260409, with frequent updates often tied to the NCNN project's release cycle.

pip install pnnx
INSTALL
IMPORT
SIG · PNNX
P
pnnx
ai-mlpythonv20260526
Install
65.3s avg
Import
5539ms
Disk
4890MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v20260526 · 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
musl
glibc
py 3.10
✕ build_error
✓ 75.55s
py 3.11
✕ build_error
✓ 66.3s
py 3.12
✕ build_error
✓ 62.8s
py 3.13
✕ build_error
✓ 56.65s
py 3.9
✕ build_error
✕ timeout
4890MB installed
● package 4890MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

pnnx
import pnnx
While 'pnnx' can be imported as a Python package, its primary user interface is typically through the command line tool 'pnnx'.

This quickstart demonstrates how to define a simple PyTorch model, trace it using `torch.jit.trace`, save it, and then use the `pnnx` command-line tool to convert it to the NCNN format. Ensure you have `torch` installed alongside `pnnx`.

import torch import os # 1. Define a simple PyTorch model class MyModel(torch.nn.Module): def __init__(self): super(MyModel, self).__init__() self.conv = torch.nn.Conv2d(3, 32, 3, padding=1) self.relu = torch.nn.ReLU() def forward(self, x): return self.relu(self.conv(x)) model = MyModel() dummy_input = torch.rand(1, 3, 64, 64) # 2. Trace the model using torch.jit.trace # This creates a TorchScript module which pnnx can convert. traced_model = torch.jit.trace(model, dummy_input) # 3. Save the traced model to a file model_path = "my_model.pt" traced_model.save(model_path) print(f"PyTorch model saved to {model_path}") print("\nNow, open your terminal and run the following command to convert the model:") print(f"pnnx {model_path} inputshape=[{','.join(map(str, dummy_input.shape))}] outputpath=converted_model") print("\nThis will generate NCNN model files (e.g., converted_model.param, converted_model.bin) in the 'converted_model' directory.") # You can also specify ONNX output: # print("Or for ONNX output:") # print(f"pnnx {model_path} inputshape=[{','.join(map(str, dummy_input.shape))}] outputpath=converted_model --onnx")
pnnx --version
Debug
Known issues
gotchaPNNX is primarily a command-line tool. While it exposes internal Python modules (e.g., `pnnx.converter`), most users will interact with it via the `pnnx` shell command for model conversion.
fix
Refer to the GitHub README or `pnnx --help` for correct command-line usage. Programmatic use of internal modules is advanced and less documented.
affects: All versions
gotchaPNNX relies on `torch.jit.trace` or `torch.jit.script` for model ingestion. Models with dynamic control flow (e.g., `if` statements, dynamic loops) or shape-dependent operations may not be correctly traced and will fail conversion. `torch.jit.trace` records a single execution path.
fix
Ensure your PyTorch model is TorchScript-compatible. Use `torch.jit.script` for models with control flow, or refactor models to use static shapes and operations where possible. Thoroughly test the traced model before conversion.
affects: All versions
gotchaThe `pnnx` PyPI package does not explicitly list `torch` as a dependency, meaning `pip install pnnx` will not automatically install PyTorch. However, PyTorch is absolutely essential for PNNX to function, as it processes PyTorch models.
fix
Manually install PyTorch in your environment via `pip install torch` (or `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118` for CUDA-enabled versions) before attempting to use pnnx.
affects: All versions
gotchaPNNX's versioning scheme is date-based (e.g., `20260409`), which is different from semantic versioning (e.g., 1.0.0). This can make tracking breaking changes or specific feature availability less intuitive.
fix
Always check the GitHub repository's release notes for the exact date version you are using or plan to use to understand changes and new features. Be aware that updates are frequent.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'torch'
PyTorch is not installed in the environment where pnnx is being run.
fix
Install PyTorch: `pip install torch` (or the appropriate command for your system/CUDA version).
pnnx: command not found
The 'pnnx' executable is not in your system's PATH, or pnnx was not installed correctly.
fix
Ensure `pip install pnnx` completed successfully. Verify that your environment's Python scripts directory (e.g., `~/.local/bin` or `venv/bin`) is included in your system's PATH.
Failed to parse input arguments
Incorrect command-line arguments passed to pnnx. Common mistakes include missing `inputshape` or wrong format for arguments.
fix
Consult `pnnx --help` for the correct syntax and available options. Ensure `inputshape` is correctly formatted, e.g., `inputshape=[1,3,224,224]`.
RuntimeError: Tracing a graph failed! Ensure the input to the trace is a Python function or a 'torch.nn.Module' and that the trace is a valid 'torch.jit.ScriptModule'.
The PyTorch model provided to `torch.jit.trace` or `pnnx` directly cannot be successfully traced into a TorchScript graph. This often happens with models using dynamic control flow or unsupported operations.
fix
Simplify your PyTorch model, remove dynamic elements, or ensure all operations are TorchScript-compatible. Consider using `torch.jit.script` for models with control flow, or debugging the tracing process in PyTorch directly.
Upgrade
Version history
20260526latest on PyPI · released May 26, 2026
Audit
Dependencies
torchrequiredRequired for loading, tracing, and manipulating PyTorch models.
onnxoptionalRequired if exporting models to ONNX format using the `--onnx` flag.
Agent activity
8 hits · last 30 days
node
8
Resources
pnnx — pip install pnnx · libregistry