mikefarah /yq
yq is a portable command-line YAML, JSON, XML, CSV, TOML, HCL and properties processor
★ 16,292⑂ 1,360👁 63⑃ 843● 1,635▤ 172
+2
日增长
16,292
stars
1,360
forks
63
watchers
843
prs
1,635
issues
172
releases
README
yq
!Build !Docker Pulls !Github Releases (by Release) !Go Report !CodeQL
A lightweight and portable command-line YAML, JSON, INI and XML processor. yq uses jq (a popular JSON processor) like syntax but works with yaml files as well as json, kyaml, xml, ini, properties, csv and tsv. It doesn't yet support everything jq does - but it does support the most common operations and functions, and more is being added continuously.
yq is written in Go - so you can download a dependency free binary for your platform and you are good to go! If you prefer there are a variety of package managers that can be used as well as Docker and Podman, all listed below.
Quick Usage Guide
Basic Operations
Read a value:
bash
yq '.a.b[0].c' file.yaml
Pipe from STDIN:
bash
yq '.a.b[0].c' ) (default "+directive")
--xml-keep-namespace enables keeping namespace after parsing attributes (default true)
--xml-proc-inst-prefix string prefix for xml processing instructions (e.g. ) (default "+p_")
--xml-raw-token enables using RawToken method instead Token. Commonly disables namespace translations. See https://pkg.go.dev/encoding/xmlDecoder.RawToken for details. (default true)
--xml-skip-directives skip over directives (e.g. )
--xml-skip-proc-inst skip over process instructions (e.g. )
--xml-strict-mode enables strict parsing of XML. See https://pkg.go.dev/encoding/xml for more details.
--yaml-fix-merge-anchor-to-spec Fix merge anchor to match YAML spec. Will default to true in late 2025
Use "yq [command] --help" for more information about a command.
By default, --split-exp rejects existing special-file destinations, including FIFOs and sockets, rather than replacing them. To retain legacy behaviour, including writing to a FIFO, use --security-allow-write-any-path only with trusted input.
Troubleshooting
Common Issues
PowerShell quoting issues:
powershell
Use single quotes for expressions
yq '.a.b[0].c' file.yaml
Or escape double quotes
yq ".a.b[0].c = \"value\"" file.yaml
Getting Help
- Check existing issues: GitHub Issues
- Ask questions: GitHub Discussions
- Documentation: Complete documentation
- Examples: Recipes and examples
Known Issues / Missing Features
- yq attempts to preserve comment positions and whitespace as much as possible, but it does not handle all scenarios (see https://github.com/go-yaml/yaml/tree/v3 for details)
- Powershell has its own...opinions on quoting yq
- "yes", "no" were dropped as boolean values in the yaml 1.2 standard - which is the standard yq assumes.
See tips and tricks for more common problems and solutions.Top issues
#515yq write strips completely blank lines from the output42 comments · 2020-08-13#462Preserve original indentation level for list items18 comments · 2020-06-12#566Multiline strings (or block scalars) are not preserved when they have trailing white space.13 comments · 2020-10-16#747PowerShell: Wrap example does not work12 comments · 2021-03-12#465Preserve formatting with in place writing12 comments · 2020-06-15#2466Support to set var. value from command invocation.10 comments · 2025-09-04#814😲 Emoji characters in keys & values in v4 are lost/corrupted9 comments · 2021-05-13#2194Case insensitive sort_keys8 comments · 2024-11-13
Discussions
#2976No way of adding `---` separator when a single bare document is processed (e.g. `split_doc` doesn't)1 comments · 2026-11-11#2757YQ Merge: Overwrite Header Comments Instead of Appending Them2 comments · 2026-06-24#2745When is next release happening?0 comments · 2026-06-11#2734Happy to see yq in suggestions from AI0 comments · 2026-06-05#2729How use field value as key in path?1 comments · 2026-06-02#2700How can I avoid removing line breaks when updating a YAML file?2 comments · 2026-05-08#2697Does this yq have a vcpkg port yet?1 comments · 2026-05-07#2696How can avoid adding null to missing select keys?2 comments · 2026-05-07
Latest release
v4.54.3 v4.54.3 2026-11-09- Fixed preservation of YAML aliases across documents within the same input stream, without leaking anchors between files (2956) Thanks @ingydotnet - Restricted --split-exp output paths to the current directory by default. Use --security-allow-write-any-path with trusted input to restore the previous behaviour (2965) - Fixed --inplace to reject direct updates to read-only files and replace symbolic links instead of modifying their targets. (2973)