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
GoMITCreated 2015-09-26mikefarah.gitbook.io/yq/
Download: v4.54.3v4.54.3 ↓4.54.32026-11-09
+2
Daily
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

Discussions

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)

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON