Environment:LaurentMazare Tch rs Libtorch Build Environment

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

Overview

Linux/macOS/Windows build environment requiring Rust (edition 2021), libtorch v2.10.0, and a C++17 compiler, with optional CUDA support for GPU acceleration.

Description

This environment provides the complete build and runtime context for the tch-rs crate, which wraps the PyTorch C++ API (libtorch) for Rust. The build system compiles a C++ FFI bridge using the cc crate, linking against libtorch shared or static libraries. The environment supports three operating systems (Linux, macOS, Windows) and multiple accelerator backends (CPU, CUDA, MPS, Vulkan). libtorch can be provided via system-wide installation, manual download, Python PyTorch installation, or automatic download via the `download-libtorch` feature.

Usage

Use this environment for any workflow that compiles or runs tch-rs code. Every Implementation page in this wiki requires this environment as a prerequisite. It is the mandatory build context for all MNIST training, pretrained model inference, transfer learning, JIT model loading, and LLM text generation workflows.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, or Windows	Linux checks `/usr/lib/libtorch.so` for system-wide install
Rust	Edition 2021 (stable or nightly)	CI tests both stable and nightly
C++ Compiler	C++17 capable	`-std=c++17` on Linux/macOS; `/std:c++17` on MSVC
Hardware (CPU)	Any x86_64 or aarch64	CPU-only mode is the default
Hardware (GPU)	NVIDIA GPU with CUDA	Optional; supports CUDA 11.8, 12.1, 12.4, 12.6, 12.8
Hardware (Apple)	Apple Silicon (aarch64)	Uses MPS backend; libtorch downloaded from PyPI wheel
Disk	~2 GB for libtorch	More for CUDA-enabled builds

Dependencies

System Packages

C++17 compiler (`g++` on Linux, `clang++` on macOS, MSVC on Windows)
`cmake` (for CMake-based build alternative)
`libgomp` (OpenMP; linked on Linux, not on macOS/Windows)

Rust Crate Dependencies

`torch-sys` = 0.23.0 (FFI bindings; built from source)
`lazy_static` >= 1.3.0
`libc` >= 0.2.0
`ndarray` >= 0.16.1
`rand` >= 0.8
`thiserror` >= 1
`zip` >= 0.6
`half` >= 2
`safetensors` >= 0.3.0

Optional Dependencies

`memmap2` >= 0.6.1 (for memory-mapped weight loading; required for LLaMA example)
`regex` >= 1.6.0 (required for Stable Diffusion and LLaMA examples)
`clap` >= 4.2.4 (required for LLaMA example CLI)
`serde_json` >= 1.0.96 (required for LLaMA example)
`image` >= 0.24.5 (optional Rust-native image backend)
`cpython` >= 0.7.1 (required for RL Python interop)

Libtorch (C++ Library)

Version: 2.10.0 (exact match required; enforced by `version_check()` in build.rs)
Provision methods:
- System-wide: `/usr/lib/libtorch.so` on Linux
- Manual: Set `LIBTORCH` environment variable
- Python PyTorch: Set `LIBTORCH_USE_PYTORCH=1`
- Auto-download: Enable `download-libtorch` Cargo feature

Credentials

No API tokens or credentials are required for the core library. All model weights are loaded from local files.

Quick Install

# Option 1: Auto-download libtorch (CPU)
cargo build --features download-libtorch

# Option 2: Use existing Python PyTorch install
export LIBTORCH_USE_PYTORCH=1
cargo build

# Option 3: Manual libtorch install
export LIBTORCH=/path/to/libtorch
export LD_LIBRARY_PATH=${LIBTORCH}/lib:$LD_LIBRARY_PATH
cargo build

# Option 4: With CUDA support (auto-download)
export TORCH_CUDA_VERSION=cu124
cargo build --features download-libtorch

Code Evidence

Version validation from `torch-sys/build.rs:156-170`:

const TORCH_VERSION: &str = "2.10.0";

fn version_check(version: &str) -> Result<()> {
    if env_var_rerun("LIBTORCH_BYPASS_VERSION_CHECK").is_ok() {
        return Ok(());
    }
    let version = version.trim();
    let version = match version.split_once('+') {
        None => version,
        Some((version, _)) => version,
    };
    if version != TORCH_VERSION {
        anyhow::bail!("this tch version expects PyTorch {TORCH_VERSION}, got {version}, ...")
    }
    Ok(())
}

OS detection and libtorch discovery from `torch-sys/build.rs:173-178`:

let os = match env::var("CARGO_CFG_TARGET_OS").expect("Unable to get TARGET_OS").as_str() {
    "linux" => Os::Linux,
    "windows" => Os::Windows,
    "macos" => Os::Macos,
    os => anyhow::bail!("unsupported TARGET_OS '{os}'"),
};

CUDA auto-detection from `torch-sys/build.rs:446-451`:

let use_cuda =
    si_lib.join("libtorch_cuda.so").exists() || si_lib.join("torch_cuda.dll").exists();
let use_hip =
    si_lib.join("libtorch_hip.so").exists() || si_lib.join("torch_hip.dll").exists();

Supported CUDA versions from `torch-sys/build.rs:315-320`:

"cpu" => "%2Bcpu",
"cu118" => "%2Bcu118",
"cu121" => "%2Bcu121",
"cu124" => "%2Bcu124",
"cu126" => "%2Bcu126",
"cu128" => "%2Bcu128",

Common Errors

Error Message	Cause	Solution
`cannot open shared object file: libtorch_cpu.so`	Linker cannot find libtorch at runtime	Set `LD_LIBRARY_PATH=/path/to/libtorch/lib` (Linux) or `DYLD_LIBRARY_PATH` (macOS)
`this tch version expects PyTorch 2.10.0, got X.Y.Z`	libtorch version mismatch	Install libtorch v2.10.0 or set `LIBTORCH_BYPASS_VERSION_CHECK=1`
`Cannot find a libtorch install`	No libtorch found and `download-libtorch` not enabled	Set `LIBTORCH` env var, use `LIBTORCH_USE_PYTORCH=1`, or add `download-libtorch` feature
`unsupported TARGET_OS`	Compiling for unsupported platform	Only Linux, macOS, and Windows are supported
Segfault on Windows	Debug/release ABI mismatch	Use matching debug/release libtorch; use MSVC toolchain, not MinGW

Compatibility Notes

Windows: Debug and release builds of libtorch are not ABI-compatible. Use MSVC Rust toolchain (`stable-x86_64-pc-windows-msvc`), not MinGW.
macOS aarch64 (Apple Silicon): libtorch is downloaded from the PyPI wheel (`cp311-none-macosx_11_0_arm64.whl`). Pre-built C++ libtorch binaries are not available for ARM macOS.
macOS x86_64: Uses standard CPU-only libtorch download.
CUDA on macOS: Not supported. CUDA pre-built binaries are only available for Linux and Windows.
Static linking: Set `LIBTORCH_STATIC=1`. Requires manually building libtorch with `BUILD_SHARED_LIBS=OFF`. Only tested on CPU builds.
CXX11 ABI: Controlled via `LIBTORCH_CXX11_ABI` env var (defaults to `1`). Must match the libtorch build.
ROCm/HIP: Build system detects `libtorch_hip.so` and links accordingly. Supported as alternative GPU backend.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment