The fork in the road
You have a backend idea. You need to serve JSON, handle authentication, and route requests to handlers. You open your terminal, type cargo new, and immediately hit a wall. Two names dominate the Rust web ecosystem: Axum and Actix-web. Both are production-ready. Both handle thousands of concurrent connections. Both will ship your code to users without breaking.
The choice isn't about which framework is objectively superior. It's about which architecture matches how you want to structure your application. One treats your server as a pipeline of composable layers. The other treats it as a highly tuned event loop with explicit state passing. Pick the wrong one for your team's rhythm and you'll spend weeks fighting the framework instead of building features.
Two different engines under the hood
Think of these frameworks like two different vehicle platforms. Actix-web is a manual transmission sports car. You get direct access to the clutch, the gear shift, and the differential. You decide exactly when torque transfers to the wheels. The trade-off is that you have to manage the mechanics yourself. Axum is a modern electric platform with integrated driver assistance. The steering, braking, and navigation are woven into a single cohesive system. You tell it where to go, and it coordinates the subsystems automatically.
Actix-web was born from the actor model. Its runtime, actix-rt, manages an event loop that dispatches tasks to workers. The web layer sits on top of that loop and gives you explicit control over request parsing, response building, and state sharing. You pass data around using web::Data, which is essentially a thread-safe reference wrapper. The framework expects you to be deliberate about what each handler receives and returns.
Axum was built by the Tokio team. It sits directly on the Tokio runtime and uses Tower for middleware. Tower is a library for building stacks of reusable, composable components. Axum treats routing, extraction, and middleware as a single type-safe pipeline. When you define a route, you're not just attaching a function to a URL. You're declaring a contract about what data the handler expects, how it should be extracted from the request, and what middleware should run before and after.
Both approaches compile to zero-cost abstractions. The difference lives in your editor, your error messages, and how you organize shared state.
The minimal setup
Here is the bare minimum to get a server listening. Notice how the two frameworks structure their entry points.
// Axum: Modular and ergonomic
use axum::{routing::get, Router};
/// Start the Axum server on port 3000 with a single root route.
#[tokio::main]
async fn main() {
// Build a router that maps "/" to a GET handler.
// The closure returns a string, which Axum automatically converts to a response.
let app = Router::new().route("/", get(|| async { "Hello, Axum!" }));
// Bind to all interfaces on port 3000.
// Tokio's TcpListener handles the low-level socket setup.
let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
// Pass the listener and router to Axum's serve function.
// This blocks the current task until the process exits.
axum::serve(listener, app).await.unwrap();
}
// Actix-web: High performance and explicit
use actix_web::{web, App, HttpServer, HttpResponse, Responder};
/// Start the Actix server on port 8080 with a single root route.
#[actix_web::main]
async fn main() -> std::io::Result<()> {
// HttpServer creates a factory that spawns worker processes.
// The closure runs once per worker to configure the app.
HttpServer::new(|| {
// App::new() creates a fresh application instance for this worker.
// web::get() specifies the HTTP method.
// .to() attaches the handler function.
App::new().route("/", web::get().to(|| async { HttpResponse::Ok().body("Hello, Actix!") }))
})
.bind("127.0.0.1:8080")?
.run()
.await
}
Axum builds a single Router value and hands it to a serve function. Actix builds a factory closure that runs inside each worker process, then binds and runs the server. The structural difference already hints at how they handle concurrency and state.
How the request actually travels
When a client sends an HTTP request, the framework has to parse headers, match a route, extract parameters, run middleware, call your handler, and serialize the response. The two frameworks orchestrate these steps differently.
Actix-web processes requests through a chain of services. Each route is a service. Middleware wraps services. When a request arrives, Actix dispatches it to a worker, matches the path against the route table, and feeds the request into the service chain. You control the chain explicitly. If you want logging, you add actix_web::middleware::Logger. If you want compression, you add Compress. Each middleware receives the request, optionally transforms it, calls the next service, and optionally transforms the response. The state you want available to handlers lives in web::Data<AppState>, which you insert into the App builder. Every handler that needs state must declare it as a parameter. The framework clones the Data wrapper for each request. The underlying data is shared via Arc.
Axum processes requests through Tower middleware. Tower defines a Service trait that takes a request and returns a future resolving to a response. Axum's Router implements Service. When you add middleware with .layer(), you're wrapping the router in a new service. The request flows through the layers like an onion. Extractors handle the heavy lifting of parsing. Instead of manually pulling data from the request, you declare what you want as function parameters. Axum matches the parameter types against a registry of extractors. If you ask for String, it reads the body. If you ask for Path<String>, it pulls the path parameter. If you ask for State<AppState>, it injects the shared state. The compiler verifies that every extractor trait bound is satisfied before the code runs.
The result is that Axum shifts complexity from runtime dispatch to compile-time type checking. Actix shifts it toward explicit service composition and runtime configuration.
Handling real data and state
Real applications need shared state. Database pools, configuration, caches, and background task handles all live outside individual requests. Here is how each framework structures a route that reads state and returns JSON.
// Axum: Type-safe extraction and state injection
use axum::{
extract::State,
response::Json,
routing::get,
Router,
};
use serde::Serialize;
use std::sync::Arc;
/// Application state shared across all handlers.
#[derive(Clone)]
struct AppState {
db_pool: String, // Placeholder for a real connection pool
}
/// Response structure for the user endpoint.
#[derive(Serialize)]
struct UserResponse {
id: u32,
name: String,
}
/// Fetch a user by ID from the simulated database.
async fn get_user(
// State extracts the shared application state.
// Axum clones the Arc internally, so this is cheap.
State(state): State<Arc<AppState>>,
// Path extracts the "id" parameter from the URL.
// The compiler verifies the route defines this parameter.
axum::extract::Path(id): axum::extract::Path<u32>,
) -> Json<UserResponse> {
// Simulate a database lookup using the shared state.
let name = format!("User-{}", id);
Json(UserResponse { id, name })
}
/// Build the router with shared state and a parameterized route.
fn build_router() -> Router {
// Wrap state in Arc so it can be shared across async tasks.
// Axum's State extractor expects a Clone type.
let state = Arc::new(AppState { db_pool: "postgres://localhost".to_string() });
// .with_state() attaches the state to the entire router.
// All child routes inherit it automatically.
Router::new()
.route("/users/{id}", get(get_user))
.with_state(state)
}
// Actix-web: Explicit data passing and macro routing
use actix_web::{web, App, HttpResponse, HttpServer, Result};
use serde::Serialize;
use std::sync::Arc;
/// Application state shared across all handlers.
struct AppState {
db_pool: String, // Placeholder for a real connection pool
}
/// Response structure for the user endpoint.
#[derive(Serialize)]
struct UserResponse {
id: u32,
name: String,
}
/// Fetch a user by ID from the simulated database.
async fn get_user(
// web::Data provides thread-safe access to shared state.
// Actix clones the Data wrapper per request, not the inner data.
state: web::Data<AppState>,
// web::Path extracts route parameters into a struct or tuple.
// The framework parses the URL segment at runtime.
path: web::Path<u32>,
) -> Result<HttpResponse> {
let id = path.into_inner();
let name = format!("User-{}", id);
// Build the response manually.
// Actix gives you full control over status codes and headers.
Ok(HttpResponse::Ok()
.json(UserResponse { id, name }))
}
/// Configure the server with shared state and a parameterized route.
fn build_app() -> App<web::Data<AppState>> {
// Wrap state in Data so it can be shared across workers.
// Data uses Arc internally for thread safety.
let state = web::Data::new(AppState { db_pool: "postgres://localhost".to_string() });
// .app_data() registers the state with the application.
// Handlers must explicitly request it as a parameter.
App::new()
.app_data(state)
.route("/users/{id}", web::get().to(get_user))
}
The patterns are functionally identical but philosophically different. Axum bakes extraction into the function signature. Actix expects you to assemble the request components explicitly. Both approaches scale to production. The community convention for Axum is to keep state behind Arc<T> and use .with_state() at the router level. The convention for Actix is to use web::Data<T> and register it with .app_data(). Both avoid copying heavy data on every request.
Where beginners trip
The biggest friction point is trait bounds. Axum's extractors rely on the FromRequest trait. If you ask for a type that doesn't implement it, the compiler rejects you with E0277 (trait bound not satisfied). You'll see this when you forget to derive Deserialize for a JSON body, or when you try to extract a custom struct without implementing the extractor trait. The error message points to the handler signature, not the missing derive. Add #[derive(serde::Deserialize)] and the error vanishes.
Actix trips beginners on macro hygiene and state cloning. The web::Data wrapper implements Clone, but cloning it does not copy the inner data. It bumps an Arc reference count. Newcomers often write state.db_pool.clone() inside a handler and wonder why they're paying for string allocations. The convention is to access the inner data directly through the Data deref. If you need to mutate shared state, you must wrap it in RwLock or Mutex inside the Data. Forgetting the lock results in a borrow checker error or a runtime panic, depending on how you structure it.
Another common mistake is mixing runtimes. Actix-web uses actix-rt by default. Tokio uses tokio::main. If you try to run a Tokio async function inside an Actix handler without bridging them, you'll get a runtime panic. The fix is to use actix_web::rt::spawn or switch the entire project to one runtime. Pick one event loop and stick with it.
Middleware composition also behaves differently. Axum layers wrap the entire router or specific routes. Actix middleware wraps services. If you need per-route middleware, Axum lets you attach it directly to the route builder. Actix requires you to nest apps or use guard-based routing. The mental model shifts from "wrapping a function" to "wrapping a service chain."
Treat the compiler errors as design feedback. They're telling you where your type contracts are incomplete.
Which one fits your project
Use Axum when you want type-safe routing and middleware composition that feels like modern Rust. Use Axum when your team values compile-time guarantees over runtime configuration. Use Axum when you are already using Tokio and Tower elsewhere in your stack. Use Axum when you prefer declaring extractors as function parameters instead of manually parsing requests.
Use Actix-web when you need maximum raw throughput and have measured that request latency is your bottleneck. Use Actix-web when you want explicit control over the service chain and prefer configuring middleware at the application level. Use Actix-web when you are building a highly customized HTTP server that needs fine-grained control over connection pooling, worker spawning, or TLS termination. Use Actix-web when your team is already comfortable with actor-style concurrency patterns.
Reach for Axum if you want the compiler to catch extraction mistakes before they hit production. Reach for Actix-web if you want a battle-tested framework with a mature ecosystem of third-party middleware. Neither choice locks you in. Both support standard HTTP, WebSockets, and streaming. Pick the one that matches your team's mental model.