Guide · Open source
How to use Tokio: set up an async Rust runtime and build a TCP echo server
Updated · written with AI from the project's own documentation and checked against our catalogue data
Tokio is a runtime for writing asynchronous Rust programs, such as network servers and clients, that handle many connections without waiting on each one in turn. This guide is for Rust developers who want to add Tokio to a project. By the end you will know how to enable it in Cargo.toml, write a small async TCP echo server, and know where to look next.
Tokiotokio-rs/tokio · ★ 33.6k · MIT Install options & downloads Quick start
- 1Install Rust with Cargo. Make sure you have a Rust toolchain with Cargo. The README says the current MSRV is 1.85.
- 2Add tokio to Cargo.toml. Add tokio with version 1.54.1 and features = ["full"] under [dependencies].
- 3Create the echo server. Put the TCP echo example from the README into main.rs.
- 4Run the project. Build and run your project with Cargo, then connect to 127.0.0.1:8080 with a TCP client to test the echo.
- 5Explore the examples. Look at the examples folder in the tokio repository for more patterns.
- 6Read the API docs. Use docs.rs/tokio to look up runtime, net and feature flag details.
What Tokio provides
Tokio is an event-driven, non-blocking I/O platform. Its main components are a multithreaded, work-stealing task scheduler, a reactor backed by the operating system's event queue (epoll, kqueue, IOCP, etc.), and asynchronous TCP and UDP sockets.
The README also describes it as providing timers and scheduling, so one package covers the runtime pieces needed for an async application.
- Task scheduler for running many async tasks
- Reactor built on the operating system's event queue
- Asynchronous TCP and UDP sockets
Add Tokio to your project with Cargo
Tokio is a Rust library, so you add it as a dependency in the Cargo.toml file of your Rust project. The README asks you to enable the full features of the tokio crate.
You need a Rust toolchain with Cargo. The README states the current minimum supported Rust version (MSRV) is 1.85.
- Requires the Rust toolchain with Cargo
- Current MSRV per the README: 1.85
[dependencies]
tokio = { version = "1.54.1", features = ["full"] }Write a basic TCP echo server
The README example listens on 127.0.0.1:8080 and accepts connections in a loop. Each connection is handed to tokio::spawn, which runs it as its own task. The task reads bytes from the socket and writes them back until the client closes the connection.
Put this code in your main.rs file. The #[tokio::main] attribute sets up the runtime for the async main function.
- TcpListener::bind binds the address and port
- listener.accept() waits for a new connection
- tokio::spawn runs each connection as a separate task
- Reading Ok(0) means the socket was closed
use tokio::net::TcpListener;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let listener = TcpListener::bind("127.0.0.1:8080").await?;
loop {
let (mut socket, _) = listener.accept().await?;
tokio::spawn(async move {
let mut buf = [0; 1024];
// In a loop, read data from the socket and write the data back.
loop {
let n = match socket.read(&mut buf).await {
// socket closed
Ok(0) => return,
Ok(n) => n,
Err(e) => {
eprintln!("failed to read from socket; err = {:?}", e);
return;
}
};
// Write the data back
if let Err(e) = socket.write_all(&buf[0..n]).await {
eprintln!("failed to write to socket; err = {:?}", e);
return;
}
}
});
}
}Find more examples and feature flags
The Tokio repository has more examples in its examples directory. For a larger real-world example, the README points to the mini-redis repository.
Feature flags are listed in the API documentation on docs.rs. The README links there from the Example section, so check it if you want to enable only some features instead of full.
- Examples: github.com/tokio-rs/tokio, examples folder
- Larger example: mini-redis repository
- Feature flags: docs.rs/tokio API docs
Get help and pick a version
The Guides and API documentation are the first place to look for answers. The README also names an active Tokio Discord server and a discussions page on GitHub.
The README recommends an LTS release if you want a fixed minor version. To pin one, use a tilde requirement such as ~1.51, which takes the newest 1.51.x patch release.
- Guides: tokio.rs/tokio/tutorial
- API docs: docs.rs/tokio/latest/tokio
- Discussions: GitHub discussions page for the tokio repository
tokio = { version = "~1.51", features = [...] }What people use it for
- Network servers that accept many TCP connections at once, as in the README echo server
- Async UDP applications using Tokio's UDP sockets
- Async services that need timers and scheduling in the same package
- Foundation for frameworks such as axum, hyper and tonic, which the Tokio project also maintains
Frequently asked questions
Is Tokio free to use?
Yes. The README lists the licence as MIT and links to the LICENSE file in the repository. You can use it in open-source and commercial Rust projects under that licence.
What do I need to use Tokio?
You need a Rust toolchain with Cargo. The README states the current minimum supported Rust version is 1.85. Tokio is a library, so you add it to a Rust project rather than installing a standalone program.
How do I install Tokio?
Add tokio = { version = "1.54.1", features = ["full"] } to the [dependencies] section of your Cargo.toml. Cargo downloads it when you build the project.
Can I use Tokio without Rust?
No. Tokio is a Rust library and the README describes it as requiring Rust. It does not ship downloadable binaries.
What are the alternatives to Tokio?
The README lists comparable projects as async-std, smol, monoio and glommio. This guide does not compare their performance, so check each project's documentation for its design and trade-offs.
Do I need async code if I only write simple scripts?
Probably not. The async model adds complexity, so for simple synchronous scripts Tokio brings little benefit. It is most useful for programs that handle many slow tasks or connections at once.
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
Tokio suits Rust developers building network servers, clients or other async applications that need I/O, scheduling and timers in one library. It is a poor fit for non-Rust programmers, for synchronous code that does not need concurrency, or for anyone who wants a ready-made binary app.
Install options & downloads