Python JSON Dump Newline Guide

When working with JSON in Python, you often need to write data to a file. The json.dump function is the standard way to do this. But what about newlines? How do you control line breaks in your output?

This guide covers everything about Python JSON dump newline behavior. You will learn how to format JSON files with proper newlines, handle multiline strings, and avoid common pitfalls.

By the end, you will write clean, readable JSON files every time.

What is json.dump in Python?

json.dump is a Python function that writes JSON data to a file. It takes a Python object and a file object as arguments. The function serializes the object into JSON format and writes it to the file.

The basic syntax looks like this:

import json

data = {"name": "Alice", "age": 30}
with open("output.json", "w") as f:
    json.dump(data, f)

This will write the JSON data without any newlines. The entire object appears on one line.

How Newlines Work in JSON Dump

By default, json.dump writes the JSON as a single line. This is compact but hard to read for humans. To add newlines and indentations, you use the indent parameter.

The indent parameter specifies the number of spaces for indentation. It automatically inserts newlines after each key-value pair and array element.

Here is an example:

import json

data = {
    "name": "Bob",
    "age": 25,
    "hobbies": ["reading", "coding"]
}

with open("pretty.json", "w") as f:
    json.dump(data, f, indent=2)  # Add 2-space indentation and newlines

The output file will look like this:

{
  "name": "Bob",
  "age": 25,
  "hobbies": [
    "reading",
    "coding"
  ]
}

Notice the newlines between each key-value pair and array element. This makes the file much more readable.

Using the indent Parameter for Newlines

The indent parameter is the most common way to add newlines to JSON output. You can use any non-negative integer. Common values are 2, 4, or 8 spaces.

You can also use None (default) for no newlines, or a string like "\t" for tab indentation.

Here is an example with 4-space indentation:

import json

data = {"city": "New York", "population": 8_400_000}
with open("city.json", "w") as f:
    json.dump(data, f, indent=4)

# Output file:
# {
#     "city": "New York",
#     "population": 8400000
# }

Each level of nesting adds a newline and the specified indentation.

Handling Multiline Strings in JSON

Sometimes your data contains strings with newlines. For example, a description field might have multiple lines. JSON supports this by escaping the newline as \n.

When you use json.dump, it automatically escapes newline characters in strings. Here is an example:

import json

data = {
    "title": "My Note",
    "content": "Line one.\nLine two.\nLine three."
}

with open("note.json", "w") as f:
    json.dump(data, f, indent=2)

# Output file:
# {
#   "title": "My Note",
#   "content": "Line one.\nLine two.\nLine three."
# }

The newlines in the string are preserved as \n escape sequences. When you read the file back, they become actual newlines again.

If you want to keep the actual newlines in the JSON file (not escaped), you must handle this manually. But this breaks JSON standards. Stick with the escaped version for compatibility.

Controlling Newlines with separators Parameter

The separators parameter gives you fine control over newlines. It takes a tuple of two strings: (item_separator, key_separator).

By default, these are (", ", ": ") for pretty printing with indent. You can change them to add or remove newlines.

Here is an example that removes all newlines:

import json

data = {"x": 1, "y": 2, "z": 3}
with open("compact.json", "w") as f:
    json.dump(data, f, separators=(",", ":"))

# Output: {"x":1,"y":2,"z":3}

To add custom newline behavior, you can use ",\n" as the item separator:

import json

data = {"a": 1, "b": 2, "c": 3}
with open("custom.json", "w") as f:
    json.dump(data, f, indent=2, separators=(",\n", ": "))

# Output:
# {
# "a": 1,
# "b": 2,
# "c": 3
# }

This puts each key-value pair on its own line without extra indentation for the keys.

Common Mistakes with Newlines

Beginners often forget the indent parameter. This produces a single-line JSON file that is hard to debug. Always add indent for human-readable files.

Another mistake is trying to manually add newlines to the JSON string. This can break the JSON structure. Let json.dump handle formatting.

Here is a wrong approach:

import json

data = {"key": "value"}
with open("bad.json", "w") as f:
    f.write("{")  # Manual newlines - BAD!
    f.write("\n  \"key\": \"value\"")
    f.write("\n}")

This is error-prone. Use json.dump with indent instead.

Example: Writing a List of Objects with Newlines

When you have a list of dictionaries, json.dump with indent adds newlines between each object.

Here is a complete example:

import json

# Sample data: list of user records
users = [
    {"id": 1, "name": "Alice", "email": "[email protected]"},
    {"id": 2, "name": "Bob", "email": "[email protected]"},
    {"id": 3, "name": "Charlie", "email": "[email protected]"}
]

# Write to file with newlines
with open("users.json", "w") as f:
    json.dump(users, f, indent=2)

print("File written successfully.")

The output file users.json will contain:

[
  {
    "id": 1,
    "name": "Alice",
    "email": "[email protected]"
  },
  {
    "id": 2,
    "name": "Bob",
    "email": "[email protected]"
  },
  {
    "id": 3,
    "name": "Charlie",
    "email": "[email protected]"
  }
]

Each object is separated by a newline and indented properly. This is perfect for configuration files or data exports.

Using ensure_ascii with Newlines

The ensure_ascii parameter affects how non-ASCII characters are handled. By default, it is True, which escapes all non-ASCII characters. This can include newline characters in strings.

If you set ensure_ascii=False, non-ASCII characters are written as-is. But newlines in strings are still escaped as \n.

Here is an example:

import json

data = {"text": "Café\nNew line"}
with open("unicode.json", "w") as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

# Output file:
# {
#   "text": "Café\nNew line"
# }

The newline in the string is still escaped. This is standard JSON behavior.

Conclusion

Mastering Python JSON dump newline is essential for writing clean, readable JSON files. Use the indent parameter to add newlines and indentation automatically. The separators parameter gives you extra control when needed.

Remember these key points:

• Always use indent for human-readable files.
• Let json.dump handle newlines automatically.
• Multiline strings are escaped as \n in JSON.
• Use separators for custom formatting.

With these techniques, you can write JSON files that are both valid and easy to read. Practice with your own data to get comfortable with the options.

Start using json.dump with newlines today and improve your Python JSON workflow.