Environment:Tencent Ncnn PyTorch Environment
| Knowledge Sources | |
|---|---|
| Domains | Model_Conversion, Deep_Learning |
| Last Updated | 2026-02-09 19:00 GMT |
Overview
Python environment with PyTorch >= 1.8 and PNNX for converting PyTorch models to ncnn format via TorchScript or direct Python API export.
Description
This environment provides the Python and PyTorch runtime required to export PyTorch models and convert them to ncnn's native `.param` and `.bin` format using the PNNX (PyTorch Neural Network eXchange) tool. PNNX supports both a Python API (`pnnx.export()`) and a command-line interface. It requires PyTorch >= 1.8 (with C++17 automatically enabled for PyTorch >= 2.1). The conversion pipeline produces ncnn-compatible model files that can then be optimized with ncnnoptimize and deployed on target devices.
Usage
Use this environment for the PyTorch Model Conversion and Inference workflow, specifically the TorchScript export step and the PNNX conversion step. It is the prerequisite for converting any PyTorch model (including torchvision and HuggingFace transformers models) into ncnn format.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux, Windows, macOS | Cross-platform support |
| Python | >= 3.7 (PNNX), >= 3.5 (ncnn bindings) | Python 3.7+ recommended |
| CMake | >= 3.12 | For building PNNX from source |
| C++ Compiler | C++14 (PyTorch < 2.1), C++17 (PyTorch >= 2.1) | MSVC 2015+ on Windows |
| Disk | ~5GB | PyTorch + model files |
Dependencies
System Packages
- `cmake` >= 3.12 (for building from source)
- C++ compiler with C++14/C++17 support
Python Packages
- `torch` >= 1.8 (PyTorch)
- `pnnx` (installable via pip)
- `torchvision` (optional, for vision model conversion)
- `numpy`
Credentials
No credentials required for model conversion. Optional:
- `HF_TOKEN`: HuggingFace API token if converting HuggingFace models that require authentication.
Quick Install
# Install PyTorch (adjust for your CUDA version)
pip install torch torchvision
# Install PNNX
pip install pnnx
# Verify installation
python -c "import torch; import pnnx; print(f'PyTorch {torch.__version__}')"
Code Evidence
PyTorch minimum version check from `tools/pnnx/CMakeLists.txt:58-60`:
if(Torch_VERSION VERSION_LESS "1.8")
message(FATAL_ERROR "pnnx only supports PyTorch >= 1.8")
endif()
C++17 requirement for PyTorch 2.1+ from `tools/pnnx/CMakeLists.txt:62-65`:
if(Torch_VERSION VERSION_GREATER_EQUAL "2.1")
# c++17 is required for using torch 2.1+ headers
set(CMAKE_CXX_STANDARD 17)
endif()
PNNX Python package dependency from `tools/pnnx/python/setup.py:132`:
requirements = ["torch"]
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `FATAL_ERROR pnnx only supports PyTorch >= 1.8` | PyTorch version too old | Upgrade: `pip install torch>=1.8` |
| `ModuleNotFoundError: No module named 'pnnx'` | PNNX not installed | `pip install pnnx` |
| `RuntimeError: Only input tensors are supported` | Non-contiguous tensors passed to export | Call `tensor.contiguous()` before tracing |
| TorchScript trace fails silently | Model uses dynamic control flow | Use `torch.jit.script` instead of `torch.jit.trace` |
Compatibility Notes
- PyTorch < 1.8: Not supported. Will produce a fatal CMake error.
- PyTorch >= 2.1: Requires C++17 compiler support. Automatically configured by PNNX's CMakeLists.txt.
- TorchVision: Optional dependency. Required for converting torchvision-specific operations (e.g., DeformConv2d, RoIAlign).
- ONNX Models: PNNX can also convert ONNX models directly: `pnnx model.onnx`.