Skip to main content

​
Installation

Retto can be used in three different ways depending on your needs. This guide covers installation for each platform.

​
Prerequisites

Before installing Retto, ensure you have:
  • Rust 1.75+ - Required for building from source
  • ONNX Runtime - Automatically handled by the ort crate
  • Operating System - Linux, macOS, or Windows
For GPU acceleration, you’ll need additional setup for CUDA (NVIDIA) or DirectML (Windows).

​
Rust Library (retto-core)

The core library provides OCR functionality for Rust applications.

​
Add to Cargo.toml

[dependencies]
retto-core = { version = "0.1.5", features = ["serde", "backend-ort"] }

​
Feature Flags

FeatureDescription
serdeEnable JSON serialization/deserialization
backend-ortBasic ONNX Runtime backend (CPU)
backend-ort-cudaCUDA execution provider for NVIDIA GPUs
backend-ort-directmlDirectML execution provider for Windows
backend-ort-wasmWebAssembly backend
hf-hubAutomatic model download from Hugging Face
download-modelsEmbed models in the binary

​
Verify Installation

cargo build
If the build succeeds, you’re ready to use Retto!

​
Command-Line Tool (retto-cli)

The CLI tool is perfect for batch processing images from the command line.

​
Build from Source

# Clone the repository
git clone https://github.com/NekoImageLand/retto.git
cd retto

# Build the CLI (CPU)
cargo build --release -p retto-cli

# The binary will be in target/release/retto-cli

​
Build with GPU Support

cargo build --release -p retto-cli --features backend-ort-cuda

​
Install Globally

cargo install --path retto-cli
This installs the retto-cli binary to your Cargo bin directory (usually ~/.cargo/bin).

​
Verify Installation

retto-cli --version

​
Obtain Models

The CLI requires ONNX model files. You have two options:

​
WebAssembly Package (retto-wasm)

The WebAssembly package enables OCR directly in web browsers.

​
Install from npm

npm install @nekoimageland/retto-wasm

​
Package Details

  • Package Name: @nekoimageland/retto-wasm
  • Current Version: 0.1.5
  • Bundle Size: Varies depending on whether models are embedded

​
TypeScript Support

The package includes TypeScript definitions out of the box: 
import { Retto, type RettoModel } from '@nekoimageland/retto-wasm';

​
Build from Source (Optional)

To build the WebAssembly package yourself: 
# Install dependencies
cd retto-wasm/fe
pnpm install

# Build the Rust code to WebAssembly
cd ..
cargo build --release --target wasm32-unknown-emscripten

# Build the TypeScript wrapper
cd fe
pnpm build
Building for WebAssembly requires Emscripten SDK. See the Emscripten documentation for setup instructions.

​
GPU Acceleration Setup

​
CUDA (NVIDIA GPUs)

For CUDA support, install:
  1. NVIDIA Driver - Latest version recommended
  2. CUDA Toolkit - Version 11.x or 12.x
  3. cuDNN - Compatible version with your CUDA installation
Verify CUDA is working: 
nvcc --version
nvidia-smi

​
DirectML (Windows)

DirectML support is built into Windows 10/11. Ensure you have:
  • Windows 10 version 1903 or later
  • Updated graphics drivers

​
Troubleshooting

The ort crate should automatically download ONNX Runtime. If it fails:
# Set environment variable to download a specific version
export ORT_STRATEGY=download
cargo clean
cargo build
Ensure CUDA toolkit is in your PATH:
# Linux/macOS
export PATH=/usr/local/cuda/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

# Windows (PowerShell)
$env:PATH = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.0\bin;$env:PATH"
Ensure your web server serves .wasm files with the correct MIME type:
Content-Type: application/wasm
For development servers, this is usually configured automatically.
Check your network connection and try setting a mirror:
export HF_ENDPOINT=https://hf-mirror.com

​
Next Steps

Now that Retto is installed, learn how to use it:

Quickstart Guide

Run your first OCR with complete examples for Rust, CLI, and WebAssembly

Build docs developers (and LLMs) love

Get started for freeTalk to us