When printing isn't enough
You add a println! to track a variable. The bug vanishes. You remove the print. The bug returns. This is a classic Heisenbug, often caused by timing changes or buffer flushing. Or you try to print a struct and get E0277 because the type doesn't implement Display. println! feels like a simple tool, but it exposes Rust's strict type system, its performance characteristics, and the distinction between data and its representation. Mastering debugging in Rust means understanding not just how to print, but how to print safely, efficiently, and with the right level of detail.
The two faces of output: Display and Debug
Rust separates how data is stored from how it is shown. println! requires a trait. The placeholder {} requires the type to implement Display. The placeholder {:?} requires the type to implement Debug. This isn't a limitation. It prevents accidental exposure of sensitive data and forces you to define a user-friendly view separate from the developer view.
Think of Display as the menu description. Think of Debug as the recipe. The customer sees the menu. The chef sees the recipe. You don't want the customer seeing "100g flour, 2 eggs, salt to taste". You want "Delicious omelet". Similarly, a user shouldn't see the raw memory layout of a database connection, but a developer definitely needs to see it when the connection fails.
Minimal example: Deriving Debug
Most types you write need Debug. The #[derive(Debug)] attribute generates the implementation automatically. It visits every field and prints it. If a field doesn't implement Debug, the derive fails at compile time. This is a safety net. You can't accidentally create a type that hides its internals from debugging tools.
#[derive(Debug)]
struct Point {
x: i32,
y: i32,
}
fn main() {
let p = Point { x: 1, y: 2 };
// Debug prints the struct name and field values.
println!("{:?}", p);
// Display requires a manual implementation.
// println!("{}", p); // Error: E0277
}
Derive Debug on every struct you write. You will need it.
How the compiler checks your prints
When you write println!("{:?}", p), the compiler looks for Debug::fmt. If #[derive(Debug)] is present, it generates that implementation. The generated code calls Debug::fmt on each field recursively. This means nested structs must also implement Debug.
If you try to use {} without Display, the compiler rejects you with E0277 (trait bound not satisfied). The error message tells you exactly which type is missing the trait. This happens at compile time. You never get a runtime panic because a type doesn't know how to format itself.
struct Secret {
value: String,
}
fn main() {
let s = Secret { value: "hidden".to_string() };
// Error: E0277: the trait Debug is not implemented for Secret.
// println!("{:?}", s);
// Fix: Add #[derive(Debug)] to Secret.
}
The compiler is forcing you to define how your data looks. Embrace the friction.
Realistic example: Tracing state with dbg!
For debugging, println! is often too verbose. You have to write the format string, name the variable, and hope the output matches the code. The dbg! macro solves this. It prints the file name, line number, the expression, and the value. It also returns the value, so you can chain it into existing code.
fn process(items: Vec<i32>) -> Vec<i32> {
// dbg! prints file, line, expression, and value.
// It returns the value, so you can use it in the chain.
let filtered = dbg!(items.into_iter().filter(|x| x > &0).collect::<Vec<_>>());
// You can also debug intermediate results without reassigning.
let doubled = filtered.iter().map(|x| x * 2).collect::<Vec<_>>();
dbg!(&doubled);
doubled
}
fn main() {
let data = vec![-1, 2, -3, 4, 5];
let result = process(data);
println!("Result: {:?}", result);
}
The community prefers dbg! over println! for debugging. dbg! gives you context automatically and integrates seamlessly into expressions. If dbg! output is cluttering your logs, switch to the log crate.
Format strings: Control the output
Format strings are more than placeholders. You can control width, alignment, and precision. This is useful for tables, fixed-width output, or formatting numbers.
fn main() {
let x = 42;
let name = "Alice";
// Right-align in width 10.
println!("{:>10}", x);
// Zero-pad to width 5.
println!("{:0>5}", x);
// Left-align string in width 10.
println!("{:<10}", name);
// Float precision: 2 decimal places.
println!("{:.2}", 3.14159);
// Combine width and precision.
println!("{:10.2}", 3.14159);
}
Convention aside: cargo fmt formats code, but it doesn't format strings. You control the layout. Use width specifiers to keep output aligned when values change length.
Implementing Display for user output
Sometimes Debug is too verbose. You want a user-friendly string. Implement std::fmt::Display. The fmt method takes a Formatter and returns a Result. Use the write! macro to build the output. write! is like println! but writes to a buffer instead of stdout. It's more efficient than string concatenation.
use std::fmt;
#[derive(Debug)]
struct User {
id: u32,
name: String,
password_hash: String,
}
impl fmt::Display for User {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
// Use write! to build the output incrementally.
// This is more efficient than string concatenation.
// Display controls the user-facing string. Hide sensitive fields here.
write!(f, "User {} ({})", self.name, self.id)
}
}
fn main() {
let user = User {
id: 1,
name: "Alice".to_string(),
password_hash: "hashed_secret".to_string(),
};
// Display shows the friendly format.
println!("{}", user);
// Debug shows all fields, including sensitive ones.
println!("{:?}", user);
}
Never expose sensitive data in Display. Use Debug for developers, but be aware that Debug prints everything. If you have secrets, implement Debug manually to redact them.
Pitfalls: Broken pipes, performance, and traits
println! can panic. If you pipe output to a command that closes early, like head, the write fails. Rust propagates this as a panic. This is called a broken pipe error. In robust applications, handle this. Use std::io::Write::write_all with error handling, or ignore the error if the program is about to exit.
use std::io::{self, Write};
fn safe_print(msg: &str) {
let stdout = io::stdout();
let mut handle = stdout.lock();
// Handle broken pipe errors gracefully.
if let Err(e) = handle.write_all(msg.as_bytes()) {
eprintln!("Warning: failed to write to stdout: {}", e);
}
}
Performance matters. println! locks stdout. In a multi-threaded application, threads contend for the lock. This serializes output and slows down the program. In a hot loop, println! can turn milliseconds into seconds. Remove debug prints before benchmarking.
Conditional compilation helps. Use #[cfg(debug_assertions)] to hide prints in release builds. The code is compiled out entirely. No runtime cost.
fn debug_helper() {
#[cfg(debug_assertions)]
{
println!("Debug mode active. Verbose output enabled.");
}
}
Never leave println! in production code. It's a leak of information and performance.
Decision: println!, dbg!, log, or debugger?
Use println! when you need human-readable output for a script or command-line tool where the output is the primary result. Use dbg! when you are actively debugging and need file, line, and expression context without writing boilerplate format strings. Use the log crate when you are building a library or application that requires configurable log levels, filtering, and multiple output destinations. Use a debugger like rust-gdb or lldb when you need to inspect memory layout, set conditional breakpoints, or step through execution without modifying source code.
If dbg! isn't enough, stop printing and start stepping.