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
| Task | Start here |
|---|---|
| Index, reshape, normalize or analyze numerical data | tensor, tutorials::tensors |
| Compute sensitivities or higher-order derivatives | autograd, tutorials::differentiation |
| Sample noise, latent variables or class labels | distributions |
| Build a model from layers | nn::Sequential, nn::Module |
| Extract image features | nn::Conv2d, nn::BatchNorm2d, nn::AdaptiveAvgPool2d |
| Model sequences or token relationships | nn::Lstm, nn::MultiheadAttention, nn::TransformerConfig |
| Train a regressor or classifier | nn::functional, optim::Adam, optim::Sgd |
| Batch samples or load data in workers | data::DataLoader, data::TensorDataset |
| Resume training or schedule updates | optim::OptimizerState, optim::StepLr, amp::GradScaler |
| Save or restore model parameters | nn::Sequential::save_weights, interop |
| Inspect an explicit computation graph | graph |
| Train across CPU processes or shard large parameter groups | distributed, tutorials::distributed |
| Exchange PT2/ONNX models or run a compiled TorchScript artifact | deployment, tutorials::deployment |
| Check custom gradients, time training regions or resume an experiment | testing, 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§
- Device
Capabilities - Backends that can actually be used by the current process.
- Tensor
- A tensor object.
Enums§
- Device
- A torch device.
- Device
Spec - A device request that is resolved against the linked LibTorch build.
- Kind
- The different kind of elements that a Tensor can hold.
- Reduction
- Rust
Torch Error - 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
_guardand 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.