Guide · Open source
How to use grpc-rust (Tonic): setup, examples and FAQs
Updated · written with AI from the project's own documentation and checked against our catalogue data
grpc-rust is the repository for Tonic, a Rust library for gRPC, the remote procedure call framework where one program calls functions on another over the network. This guide explains what Tonic is, what you need installed, and where to start so you can build a gRPC client or server in Rust. It is written for readers who know some Rust but may be new to gRPC.
Tonicgrpc/grpc-rust · ★ 12.5k · MIT Install options & downloads Quick start
- 1Check your Rust toolchain. Confirm you have a Rust toolchain at or above the MSRV of 1.88.
- 2Install protoc if needed. If you will use APIs such as tonic_build::compile_protos(), install the Protocol Buffers compiler, protoc.
- 3Clone the repository. Run git clone https://github.com/grpc/grpc-rust to get the source, examples and interop tests.
- 4Work through the helloworld tutorial. Follow the helloworld tutorial linked from the README for a basic client and server.
- 5Move to routeguide. Once the basics work, use the routeguide tutorial to see streaming and the other features.
- 6Check the API docs. Look up exact types and functions on docs.rs/tonic when you write your own code.
What is grpc-rust (Tonic)?
The project describes itself as a Rust implementation of gRPC, a high performance, open source, general RPC framework. Tonic is a gRPC over HTTP/2 implementation focused on high performance, interoperability, and flexibility, and it was built to have first class support of async/await.
Tonic is made of three main parts: the generic gRPC implementation, the HTTP/2 implementation (based on hyper and the tokio stack), and codegen powered by prost that builds clients and servers from Protocol Buffers definitions.
- tonic: generic gRPC and HTTP/2 client/server implementation
- tonic-build: prost based service codegen
- tonic-types: prost based gRPC utility types, including Well Known Types
- tonic-health: the standard gRPC health checking service
- tonic-reflection: a gRPC reflection implementation
- examples and interop: example services and interop tests
What do you need before you start?
You need a Rust toolchain. The minimum supported Rust version (MSRV) for tonic is 1.88.
Some code generation APIs use protoc, the Protocol Buffers compiler. The README says tonic-build uses protoc in some APIs that compile .proto files, such as tonic_build::compile_protos(). If you plan to use those, install protoc from the Protocol Buffers downloads page linked in the README.
- Rust toolchain, MSRV 1.88
- protoc (Protocol Buffers compiler), needed for some code generation APIs
Get the source and the examples
The README's install step is to clone the repository. Clone it to read the code and run the examples locally.
The README points beginners to the helloworld tutorial, which gives a basic example, and to the routeguide tutorial, which covers tonic and all its features. The examples folder has more scenarios, and the interop folder shows many gRPC features.
- helloworld tutorial: a basic first example
- routeguide tutorial: a complete example using all features
- examples folder: TLS, load balancing and bi-directional streaming
- interop folder: interop tests covering many gRPC features
git clone https://github.com/grpc/grpc-rustWhich features does Tonic support?
The README lists bi-directional streaming, high performance async IO, interoperability, TLS backed by rustls, load balancing, custom metadata, authentication, and health checking. Streaming, TLS and health checks are the features most relevant to services in production.
- Bi-directional streaming
- High performance async IO
- TLS backed by rustls
- Load balancing
- Custom metadata
- Authentication
- Health checking
Where to get help
Start with the API documentation on docs.rs/tonic. If that does not answer your question, the README points to the Tonic Discord channel. You can also open an issue on the GitHub repository with your question.
The README notes that the master branch is preparing breaking changes. For the most recently released code, it points to the 0.14.x branch.
What people use it for
- Building a Rust gRPC service that other programs call over the network
- Writing a Rust gRPC client that talks to an existing gRPC server
- Adding bi-directional streaming to a network service
- Adding TLS, authentication or health checks to a gRPC service
- Generating Rust client and server code from Protocol Buffers definitions
Frequently asked questions
Is grpc-rust free to use?
Yes. The project is licensed under the MIT license, and the README says contributions are licensed as MIT too. You can check the LICENSE file in the repository for the full terms.
What do I need to install to use grpc-rust?
You need a Rust toolchain with a minimum version of 1.88. You also need protoc, the Protocol Buffers compiler, if you use APIs such as tonic_build::compile_protos().
Is grpc-rust the same as Tonic?
Yes. The repository is grpc/grpc-rust, and the README describes the library as Tonic. The docs are published at docs.rs/tonic.
Do I need to know async Rust before using it?
The library is built around async/await, so familiarity with async Rust helps. The README does not offer a gentle introduction to async concepts, so the helloworld tutorial is the best starting point.
What are the alternatives to grpc-rust?
The project lists grpc-go, grpcio and connect-rust as comparable projects. Choose based on the language your team uses and the features you need.
Where do I get help if something fails?
Check the API documentation first. Then ask in the Tonic Discord channel linked from the README, or open an issue on the GitHub repository.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Tonic is a good choice for Rust developers who need gRPC services with async/await, streaming, TLS or health checks. It is not a fit if you do not write Rust, do not use gRPC or Protocol Buffers, or are new to async Rust and want a gentler introduction.
Install options & downloads