Skip to content
shellmap

convertfrom-json — Parse JSON into pipeable PowerShell objects across all 5 shells

Equivalents in every shell

Bashunix
curl -s https://api.example.com/users | jq '.[] | .name'

`jq` is the canonical bash JSON parser. `.[]` iterates arrays; `.field` accesses properties; `select(.role == "admin")` filters. `jq -r` strips the surrounding quotes from string output for piping into other shell tools. Install via apt / brew / dnf — usually a separate package, not coreutils.

Zshunix
curl -s https://api.example.com/users | jq '.[] | .name'

Same external `jq`. macOS needs `brew install jq` — no system jq. Zsh's `${(f)var}` line-split modifier is useful when parsing jq's newline-separated raw output back into a zsh array.

Fishunix
curl -s https://api.example.com/users | jq '.[] | .name'

Same external `jq`. Fish's `string split \n` builtin pairs naturally with `jq -r` output to produce a fish list that can be iterated cleanly via `for x in $list`.

PowerShellwindows
Get-Content users.json | ConvertFrom-Json | ForEach-Object { $_.name }

Takes a JSON string on the pipeline (or via `-InputObject`) and returns a `[PSCustomObject]` graph that you can drill into with `.field` syntax. Arrays become PowerShell arrays — `($json | ConvertFrom-Json)[0]` indexes. The cmdlet auto-detects single-object vs array input.

cmd.exewindows
powershell -NoProfile -Command "Get-Content users.json | ConvertFrom-Json | ForEach-Object { $_.name }"

cmd.exe has no JSON parser. Shell out to PowerShell (Win 7+ ships 5.1) — the `-NoProfile` flag skips $PROFILE for faster cold start. For one-shot parsing without PowerShell, install `jq` via `winget install jqlang.jq` and use the bash-style syntax.

Worked examples

Parse a JSON API response and select one field

Bash
curl -s https://api.example.com/users/1 | jq -r .name
PowerShell
(Invoke-RestMethod https://api.example.com/users/1).name

Filter an array by property and count matches

Bash
cat users.json | jq '[.[] | select(.role == "admin")] | length'
PowerShell
(Get-Content users.json | ConvertFrom-Json | Where-Object role -eq admin).Count

Preserve case-sensitive keys (PowerShell 6+ only)

Bash
echo '{"Name":"a","name":"b"}' | jq 'keys'
PowerShell
'{"Name":"a","name":"b"}' | ConvertFrom-Json -AsHashtable | ForEach-Object { $_.Keys }

Gotchas

  • Default output is `[PSCustomObject]` whose property keys are **case-INSENSITIVE** — `$obj.Name` and `$obj.name` both work. If your JSON has distinct `"Name"` and `"name"` keys, ONE of them silently shadows the other. Use `-AsHashtable` (pwsh 6+) to preserve case-sensitive keys (returns `[OrderedDictionary]`).
  • Single-element JSON arrays UNWRAP by default — `'[1]' | ConvertFrom-Json` returns `1` (a number), not `@(1)` (an array). This breaks `.Count` / `.Length` / `foreach` consumers that expect an array. Use `-NoEnumerate` (pwsh 6+) to keep single-element arrays as arrays, or wrap defensively: `@($obj | ConvertFrom-Json)`.
  • Duplicate keys: pwsh 5.1 throws on duplicate keys (`Cannot process argument because the value of argument "name" is not valid`). pwsh 7 silently overwrites with the LAST value. pwsh 7.3+ added `-DateKind` and stricter defaults — always pin pwsh version in CI for JSON-heavy scripts.
  • Dates: ISO 8601 strings that LOOK like dates are AUTO-CONVERTED to `[DateTime]` on pwsh 5.1 and early 7.x — surprising when the field was meant to stay as a string identifier. pwsh 7.4+ added `-DateKind String` to opt out; on older versions, the workaround is `-AsHashtable` + manual parsing.
  • Large JSON files: `Get-Content file.json` reads the file line-by-line and concatenates — slow on multi-MB JSON. Use `Get-Content -Raw file.json | ConvertFrom-Json` (single buffered read) for 10-100× speed-up. For multi-GB JSON, neither approach scales — fall back to `jq --stream` or a JSON streaming library.

WSL & PowerShell Core notes

pwsh`ConvertFrom-Json` is identical across platforms. `-AsHashtable` and `-NoEnumerate` are pwsh 6+ (don't use in 5.1-targeted scripts). pwsh 7.4 switched the parser to `System.Text.Json` — behaviour is mostly identical but a handful of edge cases differ (e.g. trailing commas, BOM tolerance). Test cross-version if you support both 5.1 and 7+.
WSLFrom WSL bash, `pwsh.exe -c "Get-Content win-file.json | ConvertFrom-Json"` reads via Windows paths. For Linux-side JSON, stay in bash with `jq` — round-tripping JSON through `pwsh.exe` adds 200ms+ of cold-start overhead per call.

Common tasks using convertfrom-json

Related commands