Environment:LaurentMazare Tch rs Python Interop Environment

Knowledge Sources	tch-rs PyTorch JIT Docs
Domains	Infrastructure, Deep_Learning
Last Updated	2026-02-08 13:00 GMT

Overview

Python 3 environment with PyTorch 2.10.0 required for TorchScript model export, checkpoint conversion, and optional PyTorch-based libtorch linking.

Description

Several tch-rs workflows require a Python environment as a prerequisite step. TorchScript model export (`torch.jit.trace` / `torch.jit.script`) must be performed in Python before the resulting `.pt` files can be loaded in Rust via `CModule::load`. The LLaMA checkpoint conversion script (`convert_checkpoint.py`) requires Python with PyTorch and `safetensors` to convert model weights. Additionally, the `LIBTORCH_USE_PYTORCH=1` build mode uses the Python PyTorch installation to locate libtorch headers and libraries.

Usage

Use this environment when performing TorchScript model export from Python, LLaMA weight conversion, or when building tch-rs with `LIBTORCH_USE_PYTORCH=1`. Also required for the reinforcement learning examples that interface with OpenAI Gym via Python.

System Requirements

Category	Requirement	Notes
Python	Python 3.x	`python3` on Linux/macOS, `python.exe` on Windows
Virtual Env	Optional	Build script auto-detects `VIRTUAL_ENV` and uses `python` instead of `python3`

Dependencies

Python Packages

`torch` == 2.10.0 (must match tch-rs TORCH_VERSION exactly)
`safetensors` (for LLaMA checkpoint conversion)
`torchvision` (for exporting pretrained vision models)
`numpy` (transitive dependency of torch)

For Reinforcement Learning Examples

`gym` / `gymnasium` (OpenAI Gym environment)
`atari-py` (for Atari game environments)

For Model Export Scripts

`torch.jit` (included in PyTorch; used by `test.py`, `resnet.py` export scripts)
`torch.utils.cpp_extension` (used by build system to locate include/lib paths)

Credentials

No API tokens or credentials are required. All operations are local.

Quick Install

# Install Python PyTorch (must match tch-rs version)
pip install torch==2.10.0 torchvision safetensors

# For RL examples
pip install gymnasium atari-py

# To use Python PyTorch as libtorch source
export LIBTORCH_USE_PYTORCH=1
cargo build

Code Evidence

Python introspection from `torch-sys/build.rs:14-23`:

import torch
from torch.utils import cpp_extension
print('LIBTORCH_VERSION:', torch.__version__.split('+')[0])
print('LIBTORCH_CXX11:', torch._C._GLIBCXX_USE_CXX11_ABI)
for include_path in cpp_extension.include_paths():
  print('LIBTORCH_INCLUDE:', include_path)
for library_path in cpp_extension.library_paths():
  print('LIBTORCH_LIB:', library_path)

Virtual environment detection from `torch-sys/build.rs:184-190`:

let python_interpreter = match os {
    Os::Windows => PathBuf::from("python.exe"),
    Os::Linux | Os::Macos => {
        if env::var_os("VIRTUAL_ENV").is_some() {
            PathBuf::from("python")
        } else {
            PathBuf::from("python3")
        }
    }
};

LLaMA checkpoint conversion usage from `examples/llama/convert_checkpoint.py:1-5`:

import torch
import safetensors.torch
# Converts PyTorch checkpoint to safetensors format

Common Errors

Error Message	Cause	Solution
`error running python3`	Python not found or not in PATH	Install Python 3.x and ensure it is on PATH
`no cxx11 abi returned by python`	PyTorch Python package is broken or too old	Reinstall: `pip install torch==2.10.0`
`this tch version expects PyTorch 2.10.0, got X.Y.Z`	Python PyTorch version mismatch	Install exact version: `pip install torch==2.10.0`
`ModuleNotFoundError: No module named 'safetensors'`	safetensors not installed	`pip install safetensors`

Compatibility Notes

LIBTORCH_USE_PYTORCH mode: The build system queries the active Python interpreter for PyTorch paths. If using a virtualenv, ensure it is activated before running `cargo build`.
Version pinning: The Python PyTorch version must exactly match `TORCH_VERSION` (2.10.0) unless `LIBTORCH_BYPASS_VERSION_CHECK` is set.
JIT export scripts: Located in `examples/jit/resnet.py`, `examples/jit-trace/test.py`, `examples/jit-train/resnet.py`, and `src/vision/export_model.py`. These generate `.pt` files consumed by Rust code.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment