Installation

Add Axum to your Rust project and configure the required dependencies

This guide will help you add Axum to your Rust project and configure the necessary dependencies.

Prerequisites

1. Install Rust

   Axum requires Rust 1.80 or later. Install Rust using rustup:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

   Verify your installation:

   rustc --version
   
2. Create a new project

   Create a new Rust binary project:

   cargo new my-axum-app
   cd my-axum-app
   

Add dependencies

Add Axum and Tokio to your Cargo.toml:

Minimal setup

[dependencies]
axum = "0.8.8"
tokio = { version = "1.0", features = ["full"] }

[dependencies]
axum = { version = "0.8.8", features = ["macros"] }
tokio = { version = "1.44", features = ["macros", "rt-multi-thread", "net"] }
tower = "0.5"
tower-http = { version = "0.6", features = ["trace", "compression-full"] }
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
serde = { version = "1.0", features = ["derive"] }

[dependencies]
axum = { version = "0.8.8", features = ["macros", "multipart", "ws"] }
tokio = { version = "1.44", features = ["full"] }
tower = "0.5"
tower-http = { version = "0.6", features = ["cors", "trace"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

Core dependencies

Axum

The main Axum crate provides routing, extractors, and response types.

axum = "0.8.8"

Axum uses semantic versioning. The API is stable, but we recommend pinning to a specific minor version.

Tokio

Axum requires the Tokio async runtime. At minimum, you need the net, rt, and macros features:

tokio = { version = "1.44", features = ["macros", "rt-multi-thread", "net"] }

For development, using the full feature set is convenient:

tokio = { version = "1.44", features = ["full"] }

The tokio feature is enabled by default in Axum. If you disable default features, you’ll need to enable it manually.

Optional features

Axum provides several optional features you can enable based on your needs:

JSON support

Enabled by default. Provides Json extractor and response:

axum = { version = "0.8.8", features = ["json"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

Macros

Provides derive macros for common patterns:

axum = { version = "0.8.8", features = ["macros"] }

Multipart forms

For handling file uploads:

axum = { version = "0.8.8", features = ["multipart"] }

WebSockets

For WebSocket connections:

axum = { version = "0.8.8", features = ["ws"] }

HTTP/2

Enabled by default. For HTTP/2 support:

axum = { version = "0.8.8", features = ["http2"] }

Tower dependencies

Tower

Provides core service abstractions:

tower = { version = "0.5.2", features = ["util", "timeout", "limit"] }

Tower-HTTP

Provides HTTP-specific middleware:

tower-http = { version = "0.6.8", features = [
    "trace",           # Request tracing
    "cors",            # CORS handling
    "compression-gzip", # Gzip compression
    "compression-br",  # Brotli compression
    "fs",              # Static file serving
] }

Tower-HTTP provides many useful middleware out of the box. Check the tower-http documentation for the complete list.

Observability

For production applications, add tracing:

tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

This enables structured logging and request tracing when combined with tower-http’s TraceLayer.

Complete example

Here’s a production-ready Cargo.toml:

[package]
name = "my-axum-app"
version = "0.1.0"
edition = "2021"

[dependencies]
# Core
axum = { version = "0.8.8", features = ["macros", "multipart"] }
tokio = { version = "1.44", features = ["macros", "rt-multi-thread", "net"] }

# Tower ecosystem
tower = { version = "0.5.2", features = ["util", "timeout"] }
tower-http = { version = "0.6.8", features = ["trace", "cors", "compression-gzip"] }

# Serialization
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

# Observability
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

Verify installation

Test that everything is set up correctly:

cargo check

You should see output indicating that dependencies are being downloaded and compiled.

The first build will take longer as Cargo downloads and compiles dependencies. Subsequent builds will be much faster.

Next steps

Quickstart

Build your first HTTP server with Axum