Overview
Lingvo is a framework for building neural networks in TensorFlow, aimed particularly at sequence models. It came out of Google, sits in the TensorFlow GitHub organisation, and is described in the paper "Lingvo: a Modular and Scalable Framework for Sequence-to-Sequence Modeling". Models are defined as Python parameter classes (for example `mnist.LeNet5` or `mt.wmt14_en_de.WmtEnDeTransformerBase`) and run through a single `lingvo.trainer` entry point, which handles training, evaluation jobs, checkpoints and TensorBoard event files.
Much of the repository is a set of reference model configurations organised by task: automatic speech recognition (Listen, Attend and Spell on LibriSpeech), machine translation (Transformer and RNMT models on WMT'14 English-German), language modelling (One Billion Words), image classification (LeNet-5 on MNIST) and 3D object detection from point clouds (StarNet and DeepFusion on KITTI and Waymo data). Its language-model task directory also carries the guide for training a GShard Transformer language model with one trillion parameters on Cloud TPU v3-512 using 512-way model parallelism, which is why Lingvo is often cited alongside large-scale sharded training. The repo keeps a list of the publications that used it.
It is a TensorFlow-era tool and should be approached as one. The pip package pins TensorFlow 2.13 and supports Python 3.8 to 3.10, and the README states that Lingvo releases offer no guarantees about backwards compatibility. Installing from PyPI gives you a frozen framework to build custom models on; changing the framework itself or adding custom ops means cloning the repo and building with Bazel. Docker files are provided for both routes. The project is Apache-2.0 licensed.
What it does
- A single `lingvo.trainer` entry point that runs trainer and evaluator jobs, writes checkpoints, hyper-parameter dumps, per-layer model-size analysis and TensorBoard events
- Models declared as parameter classes, so an experiment is selected by name (`--model=mnist.LeNet5`) rather than by editing training code
- Reference configurations for speech recognition, machine translation, language modelling, image classification and 3D point-cloud detection
- A documented path to GShard-style training of a trillion-parameter Transformer language model with 512-way model parallelism on Cloud TPU
- Two install routes: `pip3 install lingvo` for using the framework, or a Bazel source build for modifying it and writing custom ops, each with a Docker configuration
Getting started
The README's quick start trains a LeNet-5 on MNIST on CPU, which exercises the whole trainer / evaluator / checkpoint loop in under a minute. These are the pip-route commands; the pip package needs Python 3.8–3.10 and installs TensorFlow 2.13.
Install the pip package
The official codelab (codelabs/introduction.ipynb in the repo) walks through the same package in a notebook.
pip3 install lingvoPrepare the MNIST data
This writes `mnist.data-00000-of-00001` and `mnist.index` into /tmp/mnist.
mkdir -p /tmp/mnist
python3 -m lingvo.tools.keras2ckpt --dataset=mnistTrain the model
Download the model's params file and start the trainer. After about 20 seconds the loss should drop below 0.3 and a checkpoint is saved; stop it with Ctrl+C. Hyper-parameters, the model analysis and TensorBoard events land in /tmp/mnist/log/control, checkpoints in /tmp/mnist/log/train.
cd /tmp/mnist
curl -O https://raw.githubusercontent.com/tensorflow/lingvo/master/lingvo/tasks/image/params/mnist.py
python3 -m lingvo.trainer --run_locally=cpu --mode=sync --model=mnist.LeNet5 --logdir=/tmp/mnist/logEvaluate on the test split
In a normal setup the trainer and evaluator run at the same time as separate processes. The evaluator reports accuracy in its logs, then waits for new checkpoints; stop it with Ctrl+C.
python3 -m lingvo.trainer --job=evaler_test --run_locally=cpu --mode=sync --model=mnist.LeNet5 --logdir=/tmp/mnist/logMove on to the larger tasks
Machine translation needs a GPU cluster, and the GShard language model and StarNet 3D detector target Cloud TPUs. Each has its own README under lingvo/tasks/ (mt, lm and car) with the setup steps.
Commands and code are distilled from the project's own documentation — always check the official repo for the latest.
When to use it
- Reach for it when you are reproducing or extending published speech, translation or language-model work that was built on Lingvo
- Reach for it to study how a production-grade TensorFlow codebase structures sequence-model experiments as named, parameterised configurations
- Reach for it when you work on TensorFlow and Cloud TPU and want a reference for GShard-style model-parallel training of very large Transformers
How Lingvo compares
Lingvo alongside other open-source efficient training tools AI/TLDR tracks, ranked by GitHub stars.
| Tool | Stars | What it does |
|---|---|---|
| DeepSpeed | ★ 43.2k | A deep learning optimization library whose ZeRO memory partitioning and offloading let you train very large models across many GPUs. |
| Megatron-LM | ★ 18.2k | NVIDIA's library for training large transformer models at scale using tensor, pipeline, and sequence parallelism. |
| Accelerate | ★ 9.9k | A library that runs the same PyTorch training code across CPUs, multiple GPUs, and TPUs while handling mixed precision, FSDP, and DeepSpeed. |
| DeepSpec | ★ 7.2k | DeepSeek's codebase for training and evaluating draft models for speculative decoding, bundling data preparation, the DSpark, DFlash and Eagle3 drafters, training code and benchmarks. |
| TorchTitan | ★ 5.8k | A PyTorch-native platform for pre-training large models that combines FSDP, tensor, pipeline, and context parallelism in one codebase. |
| LightlySSL | ★ 3.8k | A modular PyTorch framework for self-supervised computer vision: losses, model heads and multi-view transforms for 20+ methods from MoCo and SimCLR to DINOv2, CAPI and LeJEPA. |
| Lingvo | ★ 2.9k | Google's TensorFlow framework for building and training sequence models, from MNIST to trillion-parameter GShard |
| Nanotron | ★ 2.8k | Hugging Face's minimal library for pre-training LLMs with 3D parallelism, designed to be readable and easy to modify. |