// converters
YAML to CSV.
Take a YAML array of maps and export it as CSV, with safe quoting of commas and quotes.
YAML input
CSV output
How YAML-to-CSV conversion works.
CSV (Comma-Separated Values) is a flat, row-based format — but YAML is often nested and hierarchical. This tool converts a YAML array of objects into CSV by extracting each object's keys as column headers and each array element as a row. Nested objects are flattened with dot notation: database.host becomes a column header.
Values containing commas, quotes, or newlines are properly quoted per RFC 4180 — the CSV standard. This prevents Excel from misinterpreting your data. The tool also escapes double quotes by doubling them (" → ""), which is the standard CSV escape mechanism.
When to use YAML-to-CSV.
Data export. When you need to export YAML data to a spreadsheet application (Excel, Google Sheets, Numbers), CSV is the universal interchange format. Copy the CSV output and paste it directly into a spreadsheet.
Data analysis. Tools like pandas, R, and SQL databases read CSV natively. Convert your YAML data to CSV before importing it for analysis, aggregation, or visualization.
API integration. Some APIs accept CSV uploads but not YAML. Convert your YAML data to CSV before sending it to an external service that requires flat, tabular data.
Input format requirements.
The YAML input must be an array of objects (a sequence of mappings). Each mapping becomes a row, and the union of all keys becomes the columns. If objects have different keys, missing values are left empty. Nested objects are flattened; arrays are converted to JSON strings within the cell.
Example input: - name: Ada\n email: [email protected]. The output will have columns name and email with one row of data.
Tabular data export workflows.
Spreadsheet export. Copy the CSV output and paste it directly into Excel, Google Sheets, or Numbers. The tool handles proper quoting so values containing commas or newlines are safely enclosed in double quotes. This prevents the spreadsheet from splitting a single value across multiple columns.
Data analysis pipelines. Tools like pandas, R, and SQL databases read CSV natively. Convert your YAML data to CSV before importing it for statistical analysis, aggregation, or visualization. The flat format is ideal for tabular operations like filtering, sorting, and grouping.
API integrations. Many external services and APIs accept CSV uploads but not YAML. Convert your YAML data to CSV before sending it to email marketing platforms, CRM systems, or data warehouses that require flat, tabular formats.
Handling nested data.
CSV is flat by nature, but YAML often contains nested objects and arrays. This tool flattens nested objects using dot notation: a key path like database.host becomes a single column header. Arrays within objects are serialized as JSON strings inside the cell, preserving the data without losing structure.
If your YAML has deeply nested structures, consider whether CSV is the right export format. For hierarchical data, YAML or JSON may be more appropriate. Use CSV export when your consumers need flat, tabular data for spreadsheet operations or database imports.
Best practices for clean output.
Ensure every YAML mapping has consistent keys before converting. If some objects have additional fields, those columns will be empty for objects without them. Clean and normalize your data first for the best results. Use the YAML formatter to standardize your input before conversion.
The CSV output uses standard RFC 4180 quoting: fields containing commas, quotes, or newlines are enclosed in double quotes, and any embedded quotes are doubled. This ensures maximum compatibility with spreadsheet applications, databases, and data processing tools.
FAQ
How do I convert a YAML array of objects to CSV?
Use `yq -p=yaml -o=csv '.[]' file.yaml` — the first row becomes the CSV header; or `miller --y2c` for a one-liner with type preservation.
How do I handle nested YAML when converting to CSV?
CSV is flat — you must flatten nested objects first with `yq '... explode(.)'` then convert; or pick specific fields with `.field.subfield` paths.
How do I convert a YAML map (not array) to CSV?
First reshape to array: `yq -p=yaml '[.]' file.yaml` then `yq -o=csv '.[] | [.key, .value]'` outputs key,value pairs as CSV rows.
My YAML-to-CSV conversion loses special characters — how to fix?
Wrap the output in proper CSV quoting (commas, newlines, quotes inside fields); use `miller` or Python's `csv` module which auto-quote per RFC 4180.
How do I exclude certain YAML fields when converting to CSV?
With `yq`: `yq -o=csv '.[] | del(.sensitive_field) | [.] file.yaml` — use `del()` or `with(select(...))` to drop fields before CSV output.