How to open a JSON file (and why double-clicking does nothing)

Someone sends you a file called export.json. You double-click it. Windows shrugs and asks which app you want to use. Or Notepad opens and shows you a single line of text three thousand characters wide with no line breaks anywhere.

Nothing is broken. This trips up people who have been writing software for years, so if it caught you out, you are in good company.

Why double-clicking does nothing

A JSON file is just a text file. That is the whole story. The .json extension does not install anything, does not register an application, and does not carry any special formatting — it is a naming convention that tells humans and programs what kind of text to expect inside. The format itself is defined by RFC 8259, and it is short enough to read in one sitting.

On Windows, the operating system decides what to launch based on a registry association for the extension. Nothing claims .json by default, so you get the "How do you want to open this file?" dialog. On macOS the same thing happens more quietly — it usually falls back to TextEdit or Xcode.

The fastest way: paste it into a viewer

If you just need to read the thing once, do not install anything. Open the file in any text editor, select all, copy, and paste it into a browser-based viewer that formats and expands it for you.

That last point is worth dwelling on. A lot of "JSON viewer" sites upload your file to a server to process it. If the export you were sent contains real user records, that is a data-handling decision you probably did not intend to make. Check before you paste.

Opening a JSON file on Windows

Right-click the file and choose Open with, then pick one of these rather than letting Windows guess:

• Notepad — always present, but it will show minified JSON as one unreadable line. Fine for a quick look at small files.
• VS Code — the practical answer. It understands JSON natively, and Shift+Alt+F reformats the file instantly.
• Notepad++ — lighter than VS Code. Install the JSTool plugin and use Plugins → JSTool → JSFormat.
• Your browser — drag the file onto a Chrome or Firefox window. Firefox in particular has a genuinely good built-in JSON viewer with collapsible nodes.

Opening a JSON file on macOS

The built-in option is TextEdit, but make it open in plain-text mode or it may try to be helpful in ways you do not want. From Terminal, these two cover almost everything:

# Pretty-print any JSON file to the screen
cat subscribers.json | python3 -m json.tool

# Or with jq, which is worth installing (brew install jq)
jq . subscribers.json

If you would rather stay in a GUI, drag the file onto a browser window, or open it in VS Code. Quick Look (spacebar in Finder) will preview it as plain text too.

Opening a JSON file on Linux

Any editor works, but the command line is faster for anything large:

# Pretty-print
jq . subscribers.json

# Page through a huge file without loading it all into an editor
jq . subscribers.json | less

# Just check whether it is valid, without printing it
jq empty subscribers.json && echo "valid"

What you are actually looking at

Once it is formatted, JSON is far less intimidating than it looks minified. Here is a small subscriber export — the same data, before and after.

[{"msisdn":"447700900142","imsi":"234150999912345","plan":"Unlimited 5G","roaming":true,"rsrp":-92},{"msisdn":"447700900458","imsi":"234150999967810","plan":"Pay As You Go","roaming":false,"rsrp":-104}]

[
  {
    "msisdn": "447700900142",
    "imsi": "234150999912345",
    "plan": "Unlimited 5G",
    "roaming": true,
    "rsrp": -92
  },
  {
    "msisdn": "447700900458",
    "imsi": "234150999967810",
    "plan": "Pay As You Go",
    "roaming": false,
    "rsrp": -104
  }
]

Identical bytes to the parser. Only the whitespace changed. That is all "formatting" or "beautifying" JSON ever means — which is why it is safe to do it to a file you were sent.

• [ ] is a list. This file holds two records.
• { } is one record with named fields.
• Values in "quotes" are text. -92 is a number, true is a boolean, and neither takes quotes.

If you have also been handed XML and are wondering why the two look so different, this comparison covers what each format is actually for. MDN's JSON guide is the best next step if you want to start working with it in code.

When the file is too big to open

At some point you get handed an export measured in hundreds of megabytes, and your editor stops responding. That is not the editor being weak — it is loading the whole file into memory, then building a syntax tree over it, then working out where every fold marker goes. Three passes over 500MB before it draws anything.

Do not open it. Ask it questions instead:

# What shape is it? Look at the first 2KB, not the file.
head -c 2000 huge.json

# How many records, without holding them all in memory
jq -c '.[]' huge.json | wc -l

# What keys does a record have? Pull exactly one out.
jq '.[0]' huge.json

# For files too big even for that, jq can stream token by token
jq --stream -c 'select(length==2)' huge.json | head -20

The jq manual is worth twenty minutes of your life. Being able to answer "how many, and what do they look like" without opening a file changes how you approach unfamiliar data — and if the file turns out to be one record per line rather than one big array, that is JSON Lines and you can process it line by line with anything at all.

The string that is actually more JSON

A specific confusion worth naming, because it looks like corruption and is not. You open a response and find this:

{
  "status": "ok",
  "payload": "{\"msisdn\":\"447700900142\",\"rsrp\":-92}"
}

Those \" sequences are not damage. payload is a string, and the string happens to contain JSON, so every quote inside it has to be escaped to survive being inside a string. This is double-encoded JSON, and it needs parsing twice:

const outer = JSON.parse(raw);         // outer.payload is still a string
const inner = JSON.parse(outer.payload); // now it is an object
inner.msisdn                             // '447700900142'

It usually means something upstream serialised an object and then handed the resulting string to a second serialiser without telling it. Occasionally that is deliberate — an opaque blob passed through a system that must not inspect it. More often it is a bug, and worth raising rather than working around forever.

If it will not open at all

If your editor opens the file but a program rejects it, the file is almost certainly text with a syntax error. In order of how often I have seen them:

1. A trailing comma after the last item. Legal in JavaScript, illegal in JSON. This is the single most common cause.
2. Single quotes instead of double. {'a': 1} is not JSON. Only " counts.
3. Comments. JSON has no // or /* */ — the grammar simply has no production for them. If someone added notes, a parser will refuse the file.
4. A BOM at the start of the file, usually from Windows Notepad saving as "UTF-8 with BOM". Invisible in your editor, fatal to some strict parsers.
5. It is actually JSON Lines — one object per line with no wrapping [ ]. Common in log exports. Each line is valid on its own; the file as a whole is not.

The short version

• A .json file is plain text. Nothing owns the extension, which is why double-clicking does nothing.
• To read one once: paste it into a browser-based viewer.
• To work with them regularly: install VS Code, or jq if you live in a terminal.
• Never edit JSON in Word. Smart quotes will break it.
• If a program rejects the file, check for a trailing comma first.