[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-5687":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":31,"readmeContent":32,"aiSummary":33,"trendingCount":16,"starSnapshotCount":16,"syncStatus":19,"lastSyncTime":34,"discoverSource":35},5687,"tch-rs","LaurentMazare\u002Ftch-rs","LaurentMazare","Rust bindings for the C++ api of PyTorch.","",null,"Rust",5416,433,50,198,0,7,38,2,71.21,"Apache License 2.0",false,"main",true,[26,27,28,29,30],"deep-learning","machine-learning","neural-network","pytorch","rust","2026-06-12 04:00:26","# tch-rs\nRust bindings for the C++ api of PyTorch. The goal of the `tch` crate is to\nprovide some thin wrappers around the C++ PyTorch api (a.k.a. libtorch). It\naims at staying as close as possible to the original C++ api. More idiomatic\nrust bindings could then be developed on top of this. The\n[documentation](https:\u002F\u002Fdocs.rs\u002Ftch\u002F) can be found on docs.rs.\n\n[![Build Status](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fworkflows\u002FContinuous%20integration\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Factions)\n[![Latest version](https:\u002F\u002Fimg.shields.io\u002Fcrates\u002Fv\u002Ftch.svg)](https:\u002F\u002Fcrates.io\u002Fcrates\u002Ftch)\n[![Documentation](https:\u002F\u002Fdocs.rs\u002Ftch\u002Fbadge.svg)](https:\u002F\u002Fdocs.rs\u002Ftch)\n[![Dependency Status](https:\u002F\u002Fdeps.rs\u002Frepo\u002Fgithub\u002FLaurentMazare\u002Ftch-rs\u002Fstatus.svg)](https:\u002F\u002Fdeps.rs\u002Frepo\u002Fgithub\u002FLaurentMazare\u002Ftch-rs)\n![License](https:\u002F\u002Fimg.shields.io\u002Fcrates\u002Fl\u002Ftch.svg)\n[changelog](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmain\u002FCHANGELOG.md)\n\n\nThe code generation part for the C api on top of libtorch comes from\n[ocaml-torch](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Focaml-torch).\n\n## Getting Started\n\nThis crate requires the C++ PyTorch library (libtorch) in version *v2.11.0* to be available on\nyour system. You can either:\n\n- Use the system-wide libtorch installation (default).\n- Install libtorch manually and let the build script know about it via the `LIBTORCH` environment variable.\n- Use a Python PyTorch install, to do this set `LIBTORCH_USE_PYTORCH=1`.\n- When a system-wide libtorch can't be found and `LIBTORCH` is not set, the\n  build script can download a pre-built binary version of libtorch by using\n  the `download-libtorch` feature. By default a CPU version is used. The\n  `TORCH_CUDA_VERSION` environment variable can be set to `cu117` in order to\n  get a pre-built binary using CUDA 11.7.\n\n### System-wide Libtorch\n\nOn linux platforms, the build script will look for a system-wide libtorch\nlibrary in `\u002Fusr\u002Flib\u002Flibtorch.so`.\n\n### Python PyTorch Install\n\nIf the `LIBTORCH_USE_PYTORCH` environment variable is set, the active python\ninterpreter is called to retrieve information about the torch python package.\nThis version is then linked against.\n\n### Libtorch Manual Install\n\n- Get `libtorch` from the\n[PyTorch website download section](https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F) and extract\nthe content of the zip file.\n- For Linux and macOS users, add the following to your `.bashrc` or equivalent, where `\u002Fpath\u002Fto\u002Flibtorch`\nis the path to the directory that was created when unzipping the file.\n```bash\nexport LIBTORCH=\u002Fpath\u002Fto\u002Flibtorch\n```\nThe header files location can also be specified separately from the shared library via\nthe following:\n```bash\n# LIBTORCH_INCLUDE must contain `include` directory.\nexport LIBTORCH_INCLUDE=\u002Fpath\u002Fto\u002Flibtorch\u002F\n# LIBTORCH_LIB must contain `lib` directory.\nexport LIBTORCH_LIB=\u002Fpath\u002Fto\u002Flibtorch\u002F\n```\n- For Windows users, assuming that `X:\\path\\to\\libtorch` is the unzipped libtorch directory.\n    - Navigate to Control Panel -> View advanced system settings -> Environment variables.\n    - Create the `LIBTORCH` variable and set it to `X:\\path\\to\\libtorch`.\n    - Append `X:\\path\\to\\libtorch\\lib` to the `Path` variable.\n\n  If you prefer to temporarily set environment variables, in PowerShell you can run\n```powershell\n$Env:LIBTORCH = \"X:\\path\\to\\libtorch\"\n$Env:Path += \";X:\\path\\to\\libtorch\\lib\"\n```\n- You should now be able to run some examples, e.g. `cargo run --example basics`.\n\n### Windows Specific Notes\n\nAs per [the pytorch docs](https:\u002F\u002Fpytorch.org\u002Fcppdocs\u002Finstalling.html) the Windows debug and release builds are not ABI-compatible. This could lead to some segfaults if the incorrect version of libtorch is used.\n\nIt is recommended to use the MSVC Rust toolchain (e.g. by installing `stable-x86_64-pc-windows-msvc` via rustup) rather than a MinGW based one as PyTorch has compatibilities issues with MinGW.\n\n### Static Linking\n\nWhen setting environment variable `LIBTORCH_STATIC=1`, `libtorch` is statically\nlinked rather than using the dynamic libraries. The pre-compiled artifacts don't\nseem to include `libtorch.a` by default so this would have to be compiled\nmanually, e.g. via the following:\n\n```bash\ngit clone -b v2.11.0 --recurse-submodule https:\u002F\u002Fgithub.com\u002Fpytorch\u002Fpytorch.git pytorch-static --depth 1\ncd pytorch-static\nUSE_CUDA=OFF BUILD_SHARED_LIBS=OFF python setup.py build\n# export LIBTORCH to point at the build directory in pytorch-static.\n```\n\n## Examples\n\n### Basic Tensor Operations\n\nThis crate provides a tensor type which wraps PyTorch tensors. Here is a minimal\nexample of how to perform some tensor operations.\n\n```rust\nuse tch::Tensor;\n\nfn main() {\n    let t = Tensor::from_slice(&[3, 1, 4, 1, 5]);\n    let t = t * 2;\n    t.print();\n}\n```\n\n### Training a Model via Gradient Descent\n\nPyTorch provides automatic differentiation for most tensor operations\nit supports. This is commonly used to train models using gradient\ndescent. The optimization is performed over variables which are created\nvia a `nn::VarStore` by defining their shapes and initializations.\n\nIn the example below `my_module` uses two variables `x1` and `x2`\nwhich initial values are 0. The forward pass applied to tensor `xs`\nreturns `xs * x1 + exp(xs) * x2`.\n\nOnce the model has been generated, a `nn::Sgd` optimizer is created.\nThen on each step of the training loop:\n\n- The forward pass is applied to a mini-batch of data.\n- A loss is computed as the mean square error between the model output and the mini-batch ground truth.\n- Finally an optimization step is performed: gradients are computed and variables from the `VarStore` are modified accordingly.\n\n\n```rust\nuse tch::nn::{Module, OptimizerConfig};\nuse tch::{kind, nn, Device, Tensor};\n\nfn my_module(p: nn::Path, dim: i64) -> impl nn::Module {\n    let x1 = p.zeros(\"x1\", &[dim]);\n    let x2 = p.zeros(\"x2\", &[dim]);\n    nn::func(move |xs| xs * &x1 + xs.exp() * &x2)\n}\n\nfn gradient_descent() {\n    let vs = nn::VarStore::new(Device::Cpu);\n    let my_module = my_module(vs.root(), 7);\n    let mut opt = nn::Sgd::default().build(&vs, 1e-2).unwrap();\n    for _idx in 1..50 {\n        \u002F\u002F Dummy mini-batches made of zeros.\n        let xs = Tensor::zeros(&[7], kind::FLOAT_CPU);\n        let ys = Tensor::zeros(&[7], kind::FLOAT_CPU);\n        let loss = (my_module.forward(&xs) - ys).pow_tensor_scalar(2).sum(kind::Kind::Float);\n        opt.backward_step(&loss);\n    }\n}\n```\n\n### Writing a Simple Neural Network\n\nThe `nn` api can be used to create neural network architectures, e.g. the following code defines\na simple model with one hidden layer and trains it on the MNIST dataset using the Adam optimizer.\n\n```rust\nuse anyhow::Result;\nuse tch::{nn, nn::Module, nn::OptimizerConfig, Device};\n\nconst IMAGE_DIM: i64 = 784;\nconst HIDDEN_NODES: i64 = 128;\nconst LABELS: i64 = 10;\n\nfn net(vs: &nn::Path) -> impl Module {\n    nn::seq()\n        .add(nn::linear(\n            vs \u002F \"layer1\",\n            IMAGE_DIM,\n            HIDDEN_NODES,\n            Default::default(),\n        ))\n        .add_fn(|xs| xs.relu())\n        .add(nn::linear(vs, HIDDEN_NODES, LABELS, Default::default()))\n}\n\npub fn run() -> Result\u003C()> {\n    let m = tch::vision::mnist::load_dir(\"data\")?;\n    let vs = nn::VarStore::new(Device::Cpu);\n    let net = net(&vs.root());\n    let mut opt = nn::Adam::default().build(&vs, 1e-3)?;\n    for epoch in 1..200 {\n        let loss = net\n            .forward(&m.train_images)\n            .cross_entropy_for_logits(&m.train_labels);\n        opt.backward_step(&loss);\n        let test_accuracy = net\n            .forward(&m.test_images)\n            .accuracy_for_logits(&m.test_labels);\n        println!(\n            \"epoch: {:4} train loss: {:8.5} test acc: {:5.2}%\",\n            epoch,\n            f64::from(&loss),\n            100. * f64::from(&test_accuracy),\n        );\n    }\n    Ok(())\n}\n```\n\nMore details on the training loop can be found in the\n[detailed tutorial](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Ftree\u002Fmaster\u002Fexamples\u002Fmnist).\n\n### Using some Pre-Trained Model\n\nThe [pretrained-models  example](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Ftree\u002Fmaster\u002Fexamples\u002Fpretrained-models\u002Fmain.rs)\nillustrates how to use some pre-trained computer vision model on an image.\nThe weights - which have been extracted from the PyTorch implementation - can be\ndownloaded here [resnet18.ot](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Freleases\u002Fdownload\u002Fmw\u002Fresnet18.ot)\nand here [resnet34.ot](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Freleases\u002Fdownload\u002Fmw\u002Fresnet34.ot).\n\nThe example can then be run via the following command:\n```bash\ncargo run --example pretrained-models -- resnet18.ot tiger.jpg\n```\nThis should print the top 5 imagenet categories for the image. The code for this example is pretty simple.\n\n```rust\n    \u002F\u002F First the image is loaded and resized to 224x224.\n    let image = imagenet::load_image_and_resize(image_file)?;\n\n    \u002F\u002F A variable store is created to hold the model parameters.\n    let vs = tch::nn::VarStore::new(tch::Device::Cpu);\n\n    \u002F\u002F Then the model is built on this variable store, and the weights are loaded.\n    let resnet18 = tch::vision::resnet::resnet18(vs.root(), imagenet::CLASS_COUNT);\n    vs.load(weight_file)?;\n\n    \u002F\u002F Apply the forward pass of the model to get the logits and convert them\n    \u002F\u002F to probabilities via a softmax.\n    let output = resnet18\n        .forward_t(&image.unsqueeze(0), \u002F*train=*\u002F false)\n        .softmax(-1);\n\n    \u002F\u002F Finally print the top 5 categories and their associated probabilities.\n    for (probability, class) in imagenet::top(&output, 5).iter() {\n        println!(\"{:50} {:5.2}%\", class, 100.0 * probability)\n    }\n```\n### Importing Pre-Trained Weights from PyTorch Using SafeTensors\n\n`safetensors` is a new simple format by HuggingFace for storing tensors. It does not rely on Python's `pickle` module, and therefore the tensors are not bound to the specific classes and the exact directory structure used when the model is saved. It is also zero-copy, which means that reading the file will require no more memory than the original file.\n\nFor more information on `safetensors`, please check out https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsafetensors\n\n#### Installing `safetensors`\n\nYou can install `safetensors` via the pip manager:\n\n```\npip install safetensors\n```\n\n#### Exporting weights in PyTorch\n\n```python\nimport torchvision\nfrom safetensors import torch as stt\n\nmodel = torchvision.models.resnet18(pretrained=True)\nstt.save_file(model.state_dict(), 'resnet18.safetensors')\n```\n\n*Note: the filename of the export must be named with  a `.safetensors` suffix for it to be properly decoded by `tch`.*\n\n#### Importing weights in `tch`\n\n```rust\nuse anyhow::Result;\nuse tch::{\n\tDevice,\n\tKind,\n\tnn::VarStore,\n\tvision::{\n\t\timagenet,\n\t\tresnet::resnet18,\n\t}\n};\n\nfn main() -> Result\u003C()> {\n\t\u002F\u002F Create the model and load the pre-trained weights\n\tlet mut vs = VarStore::new(Device::cuda_if_available());\n\tlet model = resnet18(&vs.root(), 1000);\n\tvs.load(\"resnet18.safetensors\")?;\n\t\n\t\u002F\u002F Load the image file and resize it to the usual imagenet dimension of 224x224.\n\tlet image = imagenet::load_image_and_resize224(\"dog.jpg\")?\n\t\t.to_device(vs.device());\n\n\t\u002F\u002F Apply the forward pass of the model to get the logits\n\tlet output = image\n\t\t.unsqueeze(0)\n\t\t.apply_t(&model, false)\n\t\t.softmax(-1, Kind::Float);\n\t\n\t\u002F\u002F Print the top 5 categories for this image.\n    for (probability, class) in imagenet::top(&output, 5).iter() {\n        println!(\"{:50} {:5.2}%\", class, 100.0 * probability)\n    }\n    \n    Ok(())\n}\n```\n\nFurther examples include:\n* A simplified version of\n  [char-rnn](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmaster\u002Fexamples\u002Fchar-rnn)\n  illustrating character level language modeling using Recurrent Neural Networks.\n* [Neural style transfer](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmaster\u002Fexamples\u002Fneural-style-transfer)\n  uses a pre-trained VGG-16 model to compose an image in the style of another image (pre-trained weights:\n  [vgg16.ot](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Freleases\u002Fdownload\u002Fmw\u002Fvgg16.ot)).\n* Some [ResNet examples on CIFAR-10](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Ftree\u002Fmaster\u002Fexamples\u002Fcifar).\n* A [tutorial](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Ftree\u002Fmaster\u002Fexamples\u002Fjit)\n  showing how to deploy\u002Frun some Python trained models using\n  [TorchScript JIT](https:\u002F\u002Fpytorch.org\u002Fdocs\u002Fstable\u002Fjit.html).\n* Some [Reinforcement Learning](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmaster\u002Fexamples\u002Freinforcement-learning)\n  examples using the [OpenAI Gym](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fgym) environment. This includes a policy gradient\n  example as well as an A2C implementation that can run on Atari games.\n* A [Transfer Learning Tutorial](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmaster\u002Fexamples\u002Ftransfer-learning)\n  shows how to finetune a pre-trained ResNet model on a very small dataset.\n* A [simplified version of GPT](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fblob\u002Fmaster\u002Fexamples\u002Fmin-gpt)\n  similar to minGPT.\n* A [Stable Diffusion](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Fdiffusers-rs)\n  implementation following the lines of hugginface's diffusers library.\n\nExternal material:\n* A [tutorial](http:\u002F\u002Fvegapit.com\u002Farticle\u002Fhow-to-use-torch-in-rust-with-tch-rs) showing how to use Torch to compute option prices and greeks.\n* [tchrs-opencv-webcam-inference](https:\u002F\u002Fgithub.com\u002Fmetobom\u002Ftchrs-opencv-webcam-inference) uses `tch-rs` and `opencv` to run inference\n  on a webcam feed for some Python trained model based on mobilenet v3.\n\n## FAQ\n\n### What are the best practices for Python to Rust model translations?\n\nSee some details in [this thread](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fissues\u002F549#issuecomment-1296840898).\n\n### How to get this to work on a M1\u002FM2 mac?\n\nCheck this [issue](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fissues\u002F488).\n\n### Compilation is slow, torch-sys seems to be rebuilt every time cargo gets run.\nSee this [issue](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-rs\u002Fissues\u002F596), this could\nbe caused by rust-analyzer not knowing about the proper environment variables\nlike `LIBTORCH` and `LD_LIBRARY_PATH`.\n\n### Using Rust\u002Ftch code from Python.\nIt is possible to call Rust\u002Ftch code from Python via PyO3,\n[tch-ext](https:\u002F\u002Fgithub.com\u002FLaurentMazare\u002Ftch-ext) provides an example of such\na Python extension.\n\n### Error loading shared libraries. \n\nIf you get an error about not finding some shared libraries when running the generated binaries\n(e.g. \n` error while loading shared libraries: libtorch_cpu.so: cannot open shared object file: No such file or directory`).\nYou can try adding the following to your `.bashrc` where `\u002Fpath\u002Fto\u002Flibtorch` is the path to your\nlibtorch install.\n```\n# For Linux\nexport LD_LIBRARY_PATH=\u002Fpath\u002Fto\u002Flibtorch\u002Flib:$LD_LIBRARY_PATH\n# For macOS\nexport DYLD_LIBRARY_PATH=\u002Fpath\u002Fto\u002Flibtorch\u002Flib:$DYLD_LIBRARY_PATH\n```\n\n## License\n`tch-rs` is distributed under the terms of both the MIT license\nand the Apache license (version 2.0), at your option.\n\nSee [LICENSE-APACHE](LICENSE-APACHE), [LICENSE-MIT](LICENSE-MIT) for more\ndetails.\n","tch-rs 是一个为 Rust 语言提供 PyTorch C++ API 绑定的库。该项目通过薄层封装使得 Rust 开发者能够直接调用 PyTorch 的功能，同时尽量保持与原生 C++ API 一致，便于熟悉 PyTorch 的用户快速上手。它支持深度学习模型的训练与推理，并且可以利用 GPU 加速计算。适用于需要结合 Rust 的高效性能和 PyTorch 强大机器学习能力的应用场景，如高性能计算、嵌入式系统中的AI应用等。此外，项目提供了详尽的文档和支持多种安装方式，方便开发者根据自身环境灵活选择。","2026-06-11 03:04:42","top_language"]