--- title: How to Use Serde with YAML Files in Rust summary: Use the serde_yaml crate with serde derive macros to serialize and deserialize Rust structs to and from YAML strings. lang: en slug: how-to-use-serde-with-yaml-files-in-rust published: 2026-04-17T12:05:42+00:00 updated: 2026-04-25T22:00:13+00:00 canonical: https://www.rustfaq.org/en/how-to-use-serde-with-yaml-files-in-rust/ --- # How to Use Serde with YAML Files in Rust ## When config files need to be readable You are building a command-line tool. It needs configuration. You reject JSON because curly braces and commas hurt human eyes. You reject TOML because your team already knows YAML. You pick YAML. It looks clean. It supports comments. It feels friendly. Then you write the parser. You spend three hours debugging why `yes` is being treated as a boolean instead of a string. You spend another hour figuring out why a missing optional field crashes your app instead of defaulting to false. You realize YAML is a trap for the unprepared. It promises simplicity but hides type coercion and indentation rules that break silently in other languages. Rust and Serde fix this. Serde is a serialization framework that generates code to convert between Rust types and data formats. `serde_yaml` is the crate that plugs YAML parsing into Serde. You define your Rust struct. Serde generates the parser. The compiler guarantees your fields exist. The parser guarantees the YAML matches. If the YAML is garbage, you get a typed error. Your program stays safe. ## How Serde and YAML work together Serde is not a parser. It is a macro-based code generator. When you add `#[derive(Serialize, Deserialize)]` to a struct, Serde injects implementations of the `Serialize` and `Deserialize` traits. These traits define how your type converts to and from a generic intermediate representation. `serde_yaml` implements the deserializer and serializer for that intermediate representation. It reads YAML text, builds a tree of values, and feeds them into your struct's `Deserialize` implementation. If the YAML contains a string where your struct expects a number, `serde_yaml` rejects it and returns an error. You never get a null pointer. You never get a silent type cast. You get a `Result` that forces you to handle the failure. This separation is powerful. You can swap `serde_yaml` for `serde_json` or `serde_toml` without changing your struct. The types stay the same. Only the format changes. Your config logic remains isolated from the parsing logic. ## Minimal example Start with a simple struct. Add the `serde` and `serde_yaml` dependencies. Derive the traits. Parse a string. ```toml [dependencies] serde = { version = "1.0", features = ["derive"] } serde_yaml = "0.9" ``` ```rust use serde::{Deserialize, Serialize}; // Derive Serialize and Deserialize to enable conversion. // This generates the code that maps YAML keys to struct fields. #[derive(Serialize, Deserialize, Debug)] struct Config { name: String, count: u32, } fn main() { // YAML input as a raw string literal. let yaml = r#" name: my_config count: 42 "#; // Deserialize the YAML string into the Config struct. // from_str returns a Result, forcing error handling. let config: Config = serde_yaml::from_str(yaml).expect("Failed to parse config"); // Print the parsed values to verify correctness. println!("Name: {}, Count: {}", config.name, config.count); // Serialize the struct back to YAML. // to_string returns a Result, handling potential formatting errors. let output = serde_yaml::to_string(&config).expect("Failed to serialize config"); println!("Serialized:\n{}", output); } ``` The `from_str` function returns `Result`. The `expect` call panics if parsing fails. In production code, you map the error to your application's error type instead of panicking. The compiler enforces this choice. You cannot ignore the failure. ## Realistic configuration parsing Real config files have nested sections, optional fields, and renamed keys. Serde attributes handle all of these without manual parsing code. ```rust use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize, Debug)] struct AppConfig { // Rename the YAML key to match Rust naming conventions. // The YAML uses 'app_name', but the Rust field is 'name'. #[serde(rename = "app_name")] name: String, // Use a default value if the field is missing in the YAML. // This prevents deserialization errors for optional config. #[serde(default)] debug: bool, // Nested struct for database configuration. // Serde recursively deserializes nested types. database: DatabaseConfig, } #[derive(Serialize, Deserialize, Debug)] struct DatabaseConfig { host: String, port: u16, // Option handles missing fields gracefully. // If 'password' is absent, it becomes None. password: Option, } fn main() { let yaml = r#" app_name: MyTool debug: false database: host: localhost port: 5432 "#; // Parse the YAML into the nested struct. // Missing 'password' becomes None. Missing 'debug' becomes false. let config: AppConfig = serde_yaml::from_str(yaml).expect("Invalid config"); println!("{:#?}", config); } ``` Convention aside: Always use `#[serde(default)]` for boolean flags in config files. Users expect missing flags to default to false. If you omit the attribute, a missing field causes a deserialization error. The error message tells the user their config is broken, even though the omission is valid. Default values make your tool feel robust. ## Handling dynamic YAML Sometimes you don't know the schema ahead of time. You might be parsing a plugin manifest or a generic data interchange format. In these cases, deserialize into `serde_yaml::Value`. This type represents any valid YAML value. ```rust use serde_yaml::Value; fn main() { let yaml = r#" name: tool version: 1.0 features: - logging - metrics meta: author: dev active: true "#; // Deserialize into a generic Value enum. // This captures the entire YAML structure without a predefined struct. let value: Value = serde_yaml::from_str(yaml).expect("Invalid YAML"); // Access fields using indexing. // Returns None if the key doesn't exist, preventing panics. if let Some(name) = value.get("name").and_then(|v| v.as_str()) { println!("Name: {}", name); } // Iterate over a sequence. if let Some(features) = value.get("features").and_then(|v| v.as_sequence()) { for feature in features { if let Some(f) = feature.as_str() { println!("Feature: {}", f); } } } } ``` `serde_yaml::Value` is an enum with variants for `Null`, `Bool`, `Number`, `String`, `Sequence`, and `Mapping`. You pattern match or use helper methods like `as_str` and `as_sequence` to extract data. This approach is flexible but loses compile-time safety. You must check every access at runtime. Use `Value` only when the schema is truly dynamic. Prefer structs when the shape is known. ## Pitfalls and quirks YAML has quirks that trip up developers coming from other languages. `serde_yaml` follows the YAML 1.1 specification, which differs from YAML 1.2 in subtle ways. YAML 1.1 treats `yes`, `no`, `on`, `off`, `true`, and `false` as booleans. If your config has a string field with value `yes`, `serde_yaml` parses it as a boolean. Deserialization fails because the types don't match. Quote your strings in YAML to avoid this. Write `"yes"` instead of `yes`. This forces the parser to treat the value as a string. Another pitfall is type coercion. YAML is loosely typed. A number can look like a string. `serde_yaml` tries to infer types based on your Rust struct. If your struct expects `u32` and the YAML has `count: 42.5`, the parser rejects it. It does not truncate the float. You get a clear error message. This strictness prevents silent data loss. Error handling is critical. Never unwrap in production code. Map the error to a user-friendly message. ```rust fn load_config(path: &str) -> Result { let content = std::fs::read_to_string(path) .map_err(|e| format!("Failed to read config file: {}", e))?; let config: Config = serde_yaml::from_str(&content) .map_err(|e| format!("Invalid config format: {}", e))?; Ok(config) } ``` The `map_err` calls transform low-level errors into strings your application can display. The user sees "Invalid config format" instead of a stack trace. Trust the borrow checker. It usually has a point. ## Decision: when to use YAML vs alternatives Choose your config format based on who edits it and how strict the schema needs to be. Use YAML when humans edit the config and comments matter. YAML supports inline comments and readable indentation. It is ideal for infrastructure-as-code files, Kubernetes manifests, and user-facing configuration where documentation lives inside the file. Use JSON when machines talk to machines. JSON is ubiquitous, fast, and strictly typed. It lacks comments and has verbose syntax. It is the standard for APIs and data interchange between services. Use TOML when you want strict typing and no indentation hell. TOML is designed for configuration. It is easy to parse, hard to write ambiguously, and supports types natively. It is the default for Rust projects and Cargo. Use environment variables for secrets and deployment-specific values. Never store passwords or API keys in config files. Environment variables keep secrets out of version control and allow different values per environment without changing the file. Counter-intuitive but true: the more flexible your config format, the harder it is to validate. YAML's flexibility invites errors. Enforce strict schemas with Serde structs to catch mistakes early. ## Where to go next - [How to Use serde for Any Data Format in Rust](/en/how-to-use-serde-for-any-data-format-in-rust/) - [How to Handle Default Values in Serde](/en/how-to-handle-default-values-in-serde/) - [Error: "missing field" in Serde Deserialization — How to Fix](/en/error-missing-field-in-serde-deserialization-how-to-fix/)