Quickstart

Build your first HTTP server with Axum in minutes

This guide will walk you through creating a simple HTTP server with Axum. You’ll learn the basics of routing, handlers, and serving your application.

Hello, World!

Let’s start with the simplest possible Axum application.

1. Create the project

   If you haven’t already, create a new Rust project and add dependencies:

   cargo new hello-axum
   cd hello-axum
   

   Update Cargo.toml:

   [dependencies]
   axum = "0.8.8"
   tokio = { version = "1.0", features = ["full"] }
   
2. Write the server code

   Replace the contents of src/main.rs with this code:

   use axum::{response::Html, routing::get, Router};
   
   #[tokio::main]
   async fn main() {
       // Build our application with a route
       let app = Router::new().route("/", get(handler));
   
       // Run it
       let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
           .await
           .unwrap();
       println!("listening on {}", listener.local_addr().unwrap());
       axum::serve(listener, app).await;
   }
   
   async fn handler() -> Html<&'static str> {
       Html("<h1>Hello, World!</h1>")
   }
   
3. Run the server

   Start your server:

   cargo run
   

   You should see:

   listening on 127.0.0.1:3000
   
4. Test the endpoint

   Open your browser to http://localhost:3000 or use curl:

   curl http://localhost:3000
   

   You should see:

   <h1>Hello, World!</h1>
   

The #[tokio::main] macro sets up the async runtime. All Axum handlers are async functions.

Understanding the code

Let’s break down what’s happening:

Router

let app = Router::new().route("/", get(handler));

The Router is the core of your application. You add routes using the .route() method, specifying:

• The path ("/")
• The HTTP method (get)
• The handler function (handler)

Handler

async fn handler() -> Html<&'static str> {
    Html("<h1>Hello, World!</h1>")
}

Handlers are async functions that return something that implements IntoResponse. The Html type tells Axum to set the Content-Type header to text/html.

Server

let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
    .await
    .unwrap();
axum::serve(listener, app).await;

This creates a TCP listener and serves your application on port 3000.

Multiple routes

Let’s add more routes to handle different paths and HTTP methods:

use axum::{routing::{get, post}, http::StatusCode, Json, Router};
use serde::{Deserialize, Serialize};

#[tokio::main]
async fn main() {
    // Initialize tracing
    tracing_subscriber::fmt::init();

    // Build our application with multiple routes
    let app = Router::new()
        .route("/", get(root))
        .route("/users", post(create_user));

    // Run it
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
        .await
        .unwrap();
    tracing::debug!("listening on {}", listener.local_addr().unwrap());
    axum::serve(listener, app).await;
}

// Basic handler that responds with a static string
async fn root() -> &'static str {
    "Hello, World!"
}

async fn create_user(
    // This argument tells axum to parse the request body
    // as JSON into a `CreateUser` type
    Json(payload): Json<CreateUser>,
) -> (StatusCode, Json<User>) {
    // Insert your application logic here
    let user = User {
        id: 1337,
        username: payload.username,
    };

    // This will be converted into a JSON response
    // with a status code of `201 Created`
    (StatusCode::CREATED, Json(user))
}

// The input to our `create_user` handler
#[derive(Deserialize)]
struct CreateUser {
    username: String,
}

// The output to our `create_user` handler
#[derive(Serialize)]
struct User {
    id: u64,
    username: String,
}

Add serde = { version = "1.0", features = ["derive"] } and tracing-subscriber = "0.3" to your dependencies to run this example.

Testing the JSON endpoint

Test the POST endpoint with curl:

curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"username": "alice"}'

Response:

{
  "id": 1337,
  "username": "alice"
}

Working with extractors

Axum provides extractors to parse different parts of requests:

JSON body

use axum::Json;
use serde::Deserialize;

#[derive(Deserialize)]
struct Input {
    name: String,
}

async fn handler(Json(payload): Json<Input>) -> String {
    format!("Hello, {}!", payload.name)
}

use axum::extract::Path;

async fn user_profile(Path(user_id): Path<u64>) -> String {
    format!("Profile for user {}", user_id)
}

// Route: .route("/users/:id", get(user_profile))

use axum::extract::Query;
use serde::Deserialize;

#[derive(Deserialize)]
struct Pagination {
    page: usize,
    per_page: usize,
}

async fn list_users(Query(pagination): Query<Pagination>) -> String {
    format!("Page {} with {} items", pagination.page, pagination.per_page)
}

// Example: GET /users?page=1&per_page=10

use axum::http::HeaderMap;

async fn handler(headers: HeaderMap) -> String {
    let user_agent = headers
        .get("user-agent")
        .and_then(|v| v.to_str().ok())
        .unwrap_or("unknown");
    format!("Your user agent: {}", user_agent)
}

Response types

Handlers can return different response types:

Plain text

async fn handler() -> &'static str {
    "Hello, World!"
}

use axum::Json;
use serde::Serialize;

#[derive(Serialize)]
struct Message {
    text: String,
}

async fn handler() -> Json<Message> {
    Json(Message {
        text: "Hello, World!".to_string(),
    })
}

use axum::response::Html;

async fn handler() -> Html<&'static str> {
    Html("<h1>Hello, World!</h1>")
}

use axum::http::StatusCode;

async fn handler() -> (StatusCode, &'static str) {
    (StatusCode::CREATED, "Resource created")
}

use axum::{http::StatusCode, Json};
use serde::Serialize;

#[derive(Serialize)]
struct User {
    id: u64,
    name: String,
}

async fn handler() -> Result<Json<User>, StatusCode> {
    let user = fetch_user().await
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;
    Ok(Json(user))
}

Adding middleware

Use Tower middleware to add cross-cutting concerns:

use tower_http::trace::TraceLayer;
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};

#[tokio::main]
async fn main() {
    // Initialize tracing
    tracing_subscriber::registry()
        .with(
            tracing_subscriber::EnvFilter::try_from_default_env()
                .unwrap_or_else(|_| "info".into()),
        )
        .with(tracing_subscriber::fmt::layer())
        .init();

    let app = Router::new()
        .route("/", get(handler))
        // Add middleware
        .layer(TraceLayer::new_for_http());

    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
        .await
        .unwrap();
    tracing::info!("listening on {}", listener.local_addr().unwrap());
    axum::serve(listener, app).await;
}

async fn handler() -> &'static str {
    "Hello, World!"
}

Add tower-http = { version = "0.6", features = ["trace"] } to use TraceLayer.

What’s next?

You now have a working Axum application! Here are some next steps:

Routing

Learn about advanced routing patterns and path parameters

Extractors

Deep dive into request extractors and validation

State management

Share application state across handlers

Middleware

Add authentication, logging, and other cross-cutting concerns

Full example

Here’s the complete example from this guide:

use axum::{
    routing::{get, post},
    http::StatusCode,
    Json, Router,
};
use serde::{Deserialize, Serialize};

#[tokio::main]
async fn main() {
    // Initialize tracing
    tracing_subscriber::fmt::init();

    // Build our application with a route
    let app = Router::new()
        // `GET /` goes to `root`
        .route("/", get(root))
        // `POST /users` goes to `create_user`
        .route("/users", post(create_user));

    // Run our app with hyper
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
        .await
        .unwrap();
    tracing::debug!("listening on {}", listener.local_addr().unwrap());
    axum::serve(listener, app).await;
}

// Basic handler that responds with a static string
async fn root() -> &'static str {
    "Hello, World!"
}

async fn create_user(
    // This argument tells axum to parse the request body
    // as JSON into a `CreateUser` type
    Json(payload): Json<CreateUser>,
) -> (StatusCode, Json<User>) {
    // Insert your application logic here
    let user = User {
        id: 1337,
        username: payload.username,
    };

    // This will be converted into a JSON response
    // with a status code of `201 Created`
    (StatusCode::CREATED, Json(user))
}

// The input to our `create_user` handler
#[derive(Deserialize)]
struct CreateUser {
    username: String,
}

// The output to our `create_user` handler
#[derive(Serialize)]
struct User {
    id: u64,
    username: String,
}

Find more complete examples in the Axum examples directory.