Skip to main content

Crate rusttorch

Crate rusttorch 

Source
Expand description

Train neural networks, run inference, and build tensor pipelines in Rust.

RustTorch combines Tensor operations and automatic differentiation with fallible neural-network layers, optimizers, data loaders, and model-weight storage. Computation runs through LibTorch; tensors are the same Rust types exposed by tch, so existing tensor code can be used directly. Operations with an f_ prefix return errors that can be propagated with ?.

§Choose an API for your task

TaskStart here
Index, reshape, normalize or analyze numerical datatensor, tutorials::tensors
Compute sensitivities or higher-order derivativesautograd, tutorials::differentiation
Sample noise, latent variables or class labelsdistributions
Build a model from layersnn::Sequential, nn::Module
Extract image featuresnn::Conv2d, nn::BatchNorm2d, nn::AdaptiveAvgPool2d
Model sequences or token relationshipsnn::Lstm, nn::MultiheadAttention, nn::TransformerConfig
Train a regressor or classifiernn::functional, optim::Adam, optim::Sgd
Batch samples or load data in workersdata::DataLoader, data::TensorDataset
Resume training or schedule updatesoptim::OptimizerState, optim::StepLr, amp::GradScaler
Save or restore model parametersnn::Sequential::save_weights, interop
Inspect an explicit computation graphgraph
Train across CPU processes or shard large parameter groupsdistributed, tutorials::distributed
Exchange PT2/ONNX models or run a compiled TorchScript artifactdeployment, tutorials::deployment
Check custom gradients, time training regions or resume an experimenttesting, profiling, checkpoint, tutorials::tools

Complete recipes are collected in tutorials, including image classifiers, sequence models, numerical analysis and probability models. Each recipe explains the expected shapes and when to use the API.

§Load images, audio, text, media or records

Enable the matching optional feature in your application’s Cargo.toml:

[dependencies]
rusttorch = { version = "0.4", features = ["vision", "audio", "text", "columnar"] }

vision loads images and typed annotations; audio turns waveforms into spectral features; text creates padded token batches; tabular transforms CSV/JSONL records with training-set statistics. columnar additionally reads Arrow IPC and Parquet. codec decodes timestamped media using an installed FFmpeg 8 runtime. Each package uses the shared data loader and finite data::ResourceLimits. The domain data guide shows which package and batch representation to choose.

§Work with tensors

Tensor shapes describe the axes of your data. For example, a matrix with shape [2, 3] contains two samples with three features each. Multiplying it by a [3, 1] weight matrix produces one value per sample.

use rusttorch::{Device, Kind, Result, Tensor};

let samples = Tensor::f_from_slice(&[1_f32, 2., 3., 4., 5., 6.])?
    .f_reshape([2, 3])?;
let weights = Tensor::f_ones([3, 1], (Kind::Float, Device::Cpu))?;
let totals = samples.f_matmul(&weights)?;

assert_eq!(totals.size(), [2, 1]);
assert_eq!(totals.double_value(&[0, 0]), 6.0);

§Train a model and run inference

This regressor learns one output from one input feature. A model owns its parameter store; the optimizer tracks those parameters and updates them from a scalar loss. Mean squared error is suitable for continuous targets. For class labels, use nn::functional::cross_entropy with raw class scores and integer targets.

use rusttorch::nn::{Sequential, functional};
use rusttorch::optim::Adam;
use rusttorch::{DeviceSpec, Result, Tensor, no_grad};

let mut model = Sequential::builder()
    .linear(1, 1)
    .build(DeviceSpec::Cpu)?;
let input = Tensor::f_from_slice(&[-1_f32, 0., 1., 2.])?.f_reshape([4, 1])?;
let target = Tensor::f_from_slice(&[-2_f32, 1., 4., 7.])?.f_reshape([4, 1])?;
let mut optimizer = Adam::builder()
    .learning_rate(0.05)
    .build(model.var_store())?;

model.train();
for _ in 0..100 {
    let prediction = model.forward(&input)?;
    let loss = functional::mse_loss(&prediction, &target)?;
    optimizer.backward_step(&loss)?;
}

model.eval();
let prediction = no_grad(|| model.forward(&input))?;
assert_eq!(prediction.size(), [4, 1]);

nn::Sequential::eval changes layer behavior, such as disabling dropout. no_grad separately disables gradient recording during inference. New sequential models start in training mode.

§Save and restore weights

SafeTensors files store named parameters and buffers. Rebuild the same model architecture before loading; strict loading checks parameter names, shapes, and dtypes. The file does not contain the model architecture or optimizer state. Use this pattern after training to save weights for inference:

use std::path::Path;
use rusttorch::nn::Sequential;
use rusttorch::{DeviceSpec, Result};

fn save_regressor(model: &Sequential, path: &Path) -> Result<()> {
    model.save_weights(path)
}

fn load_regressor(path: &Path) -> Result<Sequential> {
    let mut model = Sequential::builder()
        .linear(1, 1)
        .build(DeviceSpec::Cpu)?;
    model.load_weights(path)?;
    model.eval();
    Ok(model)
}

Use a path ending in .safetensors, such as regressor.safetensors. interop::StateDictMapping handles files whose parameter names differ.

§Devices and installation

The examples use CPU for portability. DeviceSpec::Auto selects an available accelerator before falling back to CPU. Explicit CUDA or MPS requests return an error if unavailable. Create or move inputs onto nn::Sequential::device before passing them to the model.

RustTorch requires a compatible LibTorch runtime. See the installation guide for setup, and the repository documentation for additional guides and the feature roadmap.

Modules§

amp
Mixed-precision execution and safe scaled-gradient updates.
audio
Decode local audio, resample on CPU, and compute differentiable spectral features with LibTorch. Samples use floating-point [channels, frames].
autograd
Differentiate calculations without changing parameter .grad() buffers.
checkpoint
Save a consistent training boundary in one atomic, non-overwriting artifact.
codec
Stream CPU-decoded video and audio from local media with explicit timestamps.
data
Load typed training batches from indexed datasets or lazy streams.
deployment
Deploy a RustTorch model
device
Runtime device discovery and strict device selection.
distributed
Coordinate CPU training processes and save portable distributed state.
distributions
Sample noise or discrete choices and evaluate their probabilities.
error
Errors returned by the fallible RustTorch API.
graph
Build models with named inputs, branching computations, and inspectable outputs.
interop
Save trained weights, restore an inference model, and match parameter names.
nn
Trainable layers and model composition for tensors.
optim
Update model parameters from gradients during training.
profiling
Measure application regions and benchmark completed tensor work.
reproducibility
Repeat stochastic application steps without sharing LibTorch’s global RNG.
tabular
Stream local records, fit preprocessing on training data, and reuse that immutable state for validation and inference.
tensor
Validated tensor workflows built from native LibTorch operations.
testing
Check tensor results and derivatives when developing models or custom operations.
text
Tokenize local text and produce padded model inputs with explicit policies.
tutorials
End-to-end recipes for building applications with RustTorch.
vision
Decode local images and keep annotations aligned through geometric transforms.

Structs§

DeviceCapabilities
Backends that can actually be used by the current process.
Tensor
A tensor object.

Enums§

Device
A torch device.
DeviceSpec
A device request that is resolved against the linked LibTorch build.
Kind
The different kind of elements that a Tensor can hold.
Reduction
RustTorchError
Recoverable configuration, graph, state, and backend failures.

Traits§

IndexOp
Native indexing syntax for tensor slices, such as tensor.i((.., 0)).

Functions§

available_devices
Probes the linked LibTorch backends without consulting Python at runtime.
manual_seed
Seeds LibTorch’s shared random generator before drawing tensors.
no_grad
Runs a closure without keeping track of gradients.
no_grad_guard
Disables gradient tracking, this will be enabled back when the returned value gets deallocated. Note that it is important to bind this to a name like _guard and not to _ as the latter would immediately drop the guard. See https://internals.rust-lang.org/t/pre-rfc-must-bind/12658/46 for more details.
resolve_device
Resolves an explicit or automatic device request.

Type Aliases§

Result
Result type used by RustTorch APIs that can fail recoverably.