The path puzzle
You're building a CLI tool that renames files in a directory. You grab the path from command-line arguments. You need to check if the file exists, append .bak to the name, and then pass the result to a function that reads the content. You try to do this with String. The compiler complains about separators. You try to pass the string to std::fs::read_to_string. It asks for a &Path. You convert, pass, and suddenly you realize you can't modify the path anymore because you passed a reference. You're stuck juggling types and conversions.
Rust splits file paths into two types to solve this exact friction. PathBuf owns the data and lets you mutate it. Path is a borrowed view that lets you read and inspect. They work together like String and &str, but with extra rules for file systems. Once you internalize the split, path handling becomes mechanical. The compiler guides you to the right type at every step.
PathBuf owns, Path views
PathBuf is the owned, mutable path type. It allocates memory on the heap. You can push components onto it, pop them off, and change the extension. It behaves like a String. If you need to store a path in a struct or return it from a function, you use PathBuf.
Path is the immutable reference type. It doesn't own anything. It points to path data stored elsewhere. You can read components, check for extensions, and join new parts virtually, but you cannot modify the underlying storage. It behaves like &str. Functions that only need to read a path should accept &Path. This allows callers to pass either a &PathBuf or a &Path without allocation.
The relationship mirrors string handling. String owns text. &str views text. PathBuf owns a path. &Path views a path. The compiler provides automatic coercion between them. When a function expects &Path, you can pass &PathBuf directly. The compiler inserts the borrow automatically. This is called deref coercion. It keeps the API flexible without forcing manual conversions everywhere.
Think of PathBuf as a physical address label you can write on. You can add a suite number. You can cross out the street name. Path is like reading the address off that label without taking the label itself. You can see the address. You can't change it. If you need to change it, you need the label.
Minimal example
use std::path::{Path, PathBuf};
fn main() {
// PathBuf owns the data. Use this when you need to build or modify a path.
let mut config_path = PathBuf::from("/etc");
// push adds a component. It handles separators automatically.
config_path.push("my_app");
config_path.push("config.toml");
// as_path borrows the PathBuf as an immutable &Path.
// This is cheap. No allocation happens.
let view: &Path = config_path.as_path();
println!("Looking for config at: {:?}", view);
}
PathBuf::from creates an owned path. push modifies it in place. as_path creates a reference. The reference points to the same memory. The compiler allows you to skip as_path in most cases because of deref coercion. If a function takes &Path, passing &config_path works identically.
How the compiler bridges the gap
Deref coercion is the mechanism that makes PathBuf and Path feel seamless. PathBuf implements Deref<Target=Path>. This tells the compiler that a PathBuf can be treated as a Path whenever a reference is needed. When you pass &PathBuf to a function expecting &Path, the compiler automatically dereferences the PathBuf to get the inner Path and then borrows it.
This coercion works for method calls too. Path has methods like exists, extension, and file_name. You can call these directly on a PathBuf. The compiler rewrites path_buf.exists() to Path::exists(&*path_buf). You get the read methods for free on the owned type.
The coercion does not work in reverse. You cannot pass a &Path where a &mut PathBuf is expected. A view cannot become an owner. If you need to modify a path, you must have a PathBuf. The compiler enforces this boundary strictly.
Convention aside: call to_path_buf when you need to convert a &Path to an owned PathBuf. This is the idiomatic way to take ownership. It signals intent clearly. Avoid clone on &Path because Path doesn't implement Clone. You must go through to_path_buf. The community treats to_path_buf as the standard bridge from view to owner.
Don't fight the coercion. If the compiler asks for &Path, give it &PathBuf. The conversion is zero-cost. Trust the borrow checker. It usually has a point.
Realistic workflow
Real code involves checking existence, handling errors, and transforming paths. Here's a pattern that appears in almost every file-processing tool.
use std::path::{Path, PathBuf};
use std::fs;
fn process_file(input_path: &Path) -> Result<PathBuf, std::io::Error> {
// Check if the path exists. Returns a bool.
if !input_path.exists() {
// Return an error if missing.
return Err(std::io::Error::new(
std::io::ErrorKind::NotFound,
"Input file does not exist",
));
}
// Create a new PathBuf for the output.
// We start with the input path to reuse the directory structure.
let mut output_path = input_path.to_path_buf();
// Change the extension. Returns a new PathBuf.
// This doesn't modify the original path.
output_path = output_path.with_extension("processed");
// Simulate work.
let content = fs::read_to_string(input_path)?;
fs::write(&output_path, format!("Processed: {}", content))?;
Ok(output_path)
}
The function accepts &Path. This is the right choice. The function reads the path. It doesn't need to modify the caller's path. Accepting &Path allows the caller to pass a PathBuf, a &PathBuf, or even a Path created from a string literal. The function returns PathBuf because it creates a new path that the caller might need to store or modify.
to_path_buf creates an owned copy. with_extension returns a new PathBuf with the extension replaced. It does not mutate the receiver. This is a common pattern. Path methods that transform the path usually return a new PathBuf. They don't modify in place. This keeps the API predictable. You can chain transformations without worrying about side effects.
Convention aside: with_extension replaces the entire extension. If the file is archive.tar.gz, calling with_extension("zip") produces archive.tar.zip, not archive.zip. The method treats the last dot as the extension boundary. If you need complex extension handling, use file_stem and rebuild the name. The standard library keeps extension logic simple.
Treat the return type as a contract. If the function produces a new path, return PathBuf. If it only reads, accept &Path. The types document the behavior.
Pitfalls and traps
Path handling has a few sharp edges. They all stem from treating paths like strings or misunderstanding the difference between join and push.
Paths are not strings
The biggest trap is using string methods on paths. Paths contain components and separators. They are not just text. If you try to manipulate a path with replace or split, you'll break on edge cases. Windows uses backslashes. Unix uses forward slashes. Some paths have trailing slashes. Some have multiple separators. String manipulation ignores all of this.
Use Path methods instead. join handles separators. push handles components. with_extension handles extensions. parent handles directories. The methods know about the platform. They produce correct paths regardless of the OS.
If you absolutely need string manipulation, convert to a string first. Use to_string_lossy() to get a Cow<str>. This handles non-UTF-8 bytes by replacing them with the replacement character. Perform your string ops. Convert back to PathBuf with PathBuf::from. This is the safe bridge. Don't reach for to_str() unless you're sure the path is valid UTF-8. to_str() returns Option<&str>. It fails on invalid bytes. to_string_lossy() always succeeds.
Convention aside: to_string_lossy() is the standard way to get a string for display or logging. It's fast and safe. The community prefers it over to_str().unwrap() because it never panics. Use it when you need to show a path to a user.
Display is missing
You'll hit a wall when you try to print a path. Rust paths aren't guaranteed to be valid UTF-8. They can contain arbitrary bytes on some platforms. Because of this, Path and PathBuf do not implement Display. If you try println!("{}", path), the compiler rejects you with E0277 (the trait std::fmt::Display is not implemented for std::path::Path).
Use {:?} for debugging. This prints the path with escapes for non-UTF-8 bytes. Use to_string_lossy() when you need a string for user output. The compiler forces you to make this choice explicitly. It prevents silent data loss when printing paths.
join versus push
join and push both add components, but they behave differently. join returns a new PathBuf. It always appends the argument. If the argument is an absolute path, join still appends it. The result might look weird, but it doesn't replace the base.
push modifies the PathBuf in place. It treats the argument as a component. If the argument is an absolute path, push replaces the entire path. This is a counter-intuitive trap. If you push("/tmp") onto "/home/user", you get "/tmp", not "/home/user/tmp". The absolute path wins.
Use join when you want to append blindly. Use push when you want component semantics and trust the input. If the input might be absolute, push will wipe your base path. join is safer for untrusted input.
If you try to call push on a &Path, the compiler rejects you with E0599 (no method named push found for reference &Path). Path is immutable. You need a PathBuf to mutate. This error saves you from accidental modifications.
Path::new borrows
Path::new creates a &Path from a borrowed string. It does not allocate. It does not copy. It just wraps the reference. If you pass a temporary string, you'll hit E0716 (temporary value dropped while borrowed). The path would dangle.
Use Path::new with string literals or borrowed variables that live long enough. Use PathBuf::from for owned data. The compiler enforces lifetimes here. It prevents dangling path references.
Treat paths as paths, not strings. The moment you reach for replace, you're fighting the OS. Use with_extension instead.
Decision matrix
Use PathBuf when you need to build a path, modify components, or own the data across function boundaries. Use &Path when you are reading a path, checking properties, or passing a path to a function that doesn't need to modify it. Use String only when you need to perform text manipulation that Path doesn't support, like regex replacement or case conversion, and convert back to PathBuf immediately. Use Path::new when you have a string literal or a borrowed string and need a quick view without allocation. Use to_path_buf when you have a &Path and need an owned PathBuf to store or modify. Use join when you want to append a component and get a new path without mutating the original. Use push when you want to mutate a PathBuf in place and the input is guaranteed to be a relative component.
Pick the type that matches your ownership needs. PathBuf owns. &Path views. Everything else is noise.