Guide · Open source
How to use warp: a Rust web server framework tutorial
Updated · written with AI from the project's own documentation and checked against our catalogue data
warp is an open-source web server framework for the Rust programming language, published under the MIT licence. It lets you describe what an incoming request must look like, such as its path, headers, query string or body, by combining small pieces called filters, then write the code that answers matching requests. This guide shows you how to add warp to a Rust project, run a first server and understand the filter model well enough to build from there.
warpseanmonstar/warp · ★ 10.4k · MIT Install options & downloads Quick start
- 1Install Rust and Cargo. Make sure a Rust toolchain with Cargo is installed, since warp is a Rust library.
- 2Add dependencies. Add tokio with features full and warp with version 0.4 and the server feature to your Cargo.toml.
- 3Create main.rs. Import warp::Filter and mark an async main function with the tokio main attribute.
- 4Define a filter. Build a route with warp::path! that matches a path with a String parameter and maps it to a response.
- 5Start the server. Pass the filter to warp::serve and call run with 127.0.0.1 and port 3030.
- 6Test the route. Request /hello/warp and confirm the response body is Hello, warp!
What warp is and what it does out of the box
The fundamental building block of warp is the Filter. Filters can be combined and composed to express rich requirements on requests, so routing and request handling are built from the same small parts.
warp provides path routing and parameter extraction, header requirements and extraction, query string deserialization, JSON and form bodies, multipart form data, static files and directories, websockets, access logging, and Gzip, Deflate and Brotli compression.
- Path routing and parameter extraction
- Header requirements and extraction
- Query string deserialization
- JSON and Form bodies
- Multipart form data
- Static Files and Directories
- Websockets
- Access logging
- Gzip, Deflate, and Brotli compression
Install warp and Tokio with Cargo
warp is a Rust library, so you need a Rust toolchain with Cargo installed. warp runs asynchronously on the Tokio runtime, so Tokio is added as a dependency alongside warp in your Cargo.toml file.
The README lists these two dependency lines. The server feature is enabled on warp.
- Prerequisites: a Rust toolchain with Cargo, and the Tokio async runtime added as a dependency
tokio = { version = "1", features = ["full"] }
warp = { version = "0.4", features = ["server"] }Write your first warp server
Create a main.rs file and import warp's Filter trait. Mark main with the Tokio macro so it runs asynchronously. Then build a filter that matches a GET request to a path containing a name, and map it to a response.
The example's route uses warp::path! with a String parameter. Passing that filter to warp::serve and calling run with an address and port starts the server on 127.0.0.1 port 3030.
- The comment in the example says GET /hello/warp returns 200 OK with the body "Hello, warp!"
- Change the address array to listen on a different port
use warp::Filter;
#[tokio::main]
async fn main() {
// GET /hello/warp => 200 OK with body "Hello, warp!"
let hello = warp::path!("hello" / String)
.map(|name| format!("Hello, {}!", name));
warp::serve(hello)
.run(([127, 0, 0, 1], 3030))
.await;
}Understand the filter model
A filter describes a condition on the request and can extract values from it. You combine filters to add more conditions, so a route can require a path, a header and a body in one expression. The handler at the end receives the extracted values.
The README does not go into detail beyond this model, so the official docs at docs.rs/warp and the examples folder on GitHub are the places to look for more patterns.
- Path filters match and extract parts of the URL, such as warp::path!
- Other filters pull out headers, query strings or bodies
- map transforms the extracted values into a response
Where to go next
Once the example runs, the docs and examples linked from the README cover the wider feature set. Start with the feature you need, such as JSON bodies or static files, and add one filter at a time.
- Read the API docs at docs.rs/warp
- Browse the examples folder in the seanmonstar/warp repository
- Project homepage: https://seanmonstar.com/blog/warp/
What people use it for
- Building a small HTTP API in Rust that routes requests by path and parses JSON bodies
- Serving static files and directories from a Rust binary
- Adding websocket endpoints alongside HTTP routes in one framework
- Reading query strings and form data into typed values for a backend service
Frequently asked questions
Is warp free to use?
Yes. warp is published under the MIT licence, as shown in the README badge and the project's LICENSE file. You can use it in commercial and open-source projects under that licence's terms.
What do I need to install warp?
You need a Rust toolchain with Cargo. You also add the Tokio async runtime as a dependency, since warp runs asynchronously. The README shows both lines to add to Cargo.toml.
Does warp support HTTP/2?
Yes. warp is built on top of hyper, and the README states that this gives you HTTP/1, HTTP/2 and asynchronous handling automatically.
Do I need to know Rust to use warp?
Yes. The README only shows Rust examples, and warp is a Rust framework. Beginners new to both Rust and async programming may find the filter model and Tokio setup take time to learn.
What are the alternatives to warp?
The project lists axum, actix-web, rocket and tide as comparable Rust projects. This guide does not benchmark them, so compare their docs against your needs.
Is warp stable enough for production?
The latest release is v0.4.1, and the README does not describe a long-term support policy. Check the project's current status and release history before depending on it for a long-lived product.
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
warp suits Rust developers who want to build HTTP APIs or web servers from small composable filters and need routing, JSON, websockets or static files in one framework. If you do not write Rust, are new to both Rust and async programming, or need a documented long-term stability guarantee, pick another option such as one of the listed alternatives.
Install options & downloads