Implementation:Tencent Ncnn Torch Jit Trace

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

Overview

External tool for serializing PyTorch models to TorchScript format, the prerequisite for PNNX conversion to ncnn.

Description

torch.jit.trace and torch.jit.script are PyTorch's built-in model serialization APIs. In the ncnn conversion pipeline, torch.jit.trace is the most commonly used method: it executes the model with a representative input tensor and records all operations into a TorchScript graph. The resulting ScriptModule is saved to a .pt file that PNNX consumes as input.

This is an External Tool Doc — the API belongs to PyTorch, not ncnn. It is documented here because it is the mandatory first step in the PyTorch-to-ncnn model conversion workflow.

Usage

Use before running PNNX conversion. The example input tensor must match the model's expected input shape and dtype. For dynamic shape models, use torch.jit.trace with a representative shape and then configure PNNX with inputshape and inputshape2 parameters.

Code Reference

Source Location

• Repository: PyTorch
• File: torch/jit/_trace.py (trace), torch/jit/_script.py (script)

Signature

import torch

# Trace a model with example input
torch.jit.trace(
    func,           # nn.Module or callable
    example_inputs, # Tensor or tuple of Tensors
    optimize=None,  # deprecated
    check_trace=True,
    check_inputs=None,
    check_tolerance=1e-5,
    strict=True
) -> torch.jit.ScriptModule

# Script a model (static analysis)
torch.jit.script(
    obj,            # nn.Module, function, or class
    optimize=None,
    _frames_up=0,
    _rcb=None
) -> torch.jit.ScriptModule

Import

import torch

I/O Contract

Inputs

Name	Type	Required	Description
func	nn.Module	Yes	The trained PyTorch model
example_inputs	Tensor	Yes	Representative input tensor matching model's expected shape

Outputs

Name	Type	Description
ScriptModule	torch.jit.ScriptModule	Serializable model, saved via .save("model.pt")
.pt file	File	TorchScript archive consumed by PNNX

Usage Examples

Trace a Classification Model

import torch
import torchvision

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

# Create example input matching expected shape
example_input = torch.randn(1, 3, 224, 224)

# Trace the model
traced_model = torch.jit.trace(model, example_input)

# Save for PNNX conversion
traced_model.save("resnet18.pt")

Trace a Detection Model (YOLOv8)

# Using ultralytics CLI
# yolo export model=yolov8n.pt format=torchscript

# Or programmatically:
from ultralytics import YOLO

model = YOLO("yolov8n.pt")
model.export(format="torchscript")
# Produces yolov8n.torchscript

Related Pages

Implements Principle

• Principle:Tencent_Ncnn_TorchScript_Export

Requires Environment

• Environment:Tencent_Ncnn_PyTorch_Environment