Write a List to a File in Python: Text, JSON, or CSV?

To write a list to a file in Python, you choose between text, JSON, or CSV based on what the data is and how it will be used: use text for simple readability, JSON for nested or mixed-type data, and CSV for tabular data meant for spreadsheets. This article explains each method with code examples, when to use which, and common pitfalls to avoid.

Why the File Format Matters

Python lists can hold numbers, strings, booleans, nested lists, and dictionaries. A plain text file stores only the string representation of the list, which is easy for a human to read but hard for a program to parse back into a list. JSON (JavaScript Object Notation) preserves the data structure and type information, so you can load it back with json.load() and get exactly the same list. CSV (Comma-Separated Values) is the standard for tabular data—rows and columns—and is what spreadsheet applications like Excel expect. Choosing the wrong format can lead to extra parsing code, data corruption, or compatibility issues.

Writing to a Plain Text File

The simplest way to write a list to a text file is to convert it to a string with str() and write that string. For example:

my_list = [1, 2, 3, 'hello']
with open('output.txt', 'w') as f:
    f.write(str(my_list))

This writes [1, 2, 3, 'hello'] as a single line. To read it back, you would need to use ast.literal_eval() to safely evaluate the string into a list, because eval() is dangerous with untrusted input. If you want each element on its own line, you can iterate:

with open('output.txt', 'w') as f:
    for item in my_list:
        f.write(f"{item}\n")

Reading that back requires splitting lines and converting types manually. Text files are best for logs, simple configuration, or when the file is meant for human reading only.

Writing to JSON

JSON is the recommended format when you need to preserve the list structure and data types. The json module handles serialization and deserialization:

import json
my_list = [1, 2.5, 'hello', True, None, [4, 5]]
with open('output.json', 'w') as f:
    json.dump(my_list, f)

To read it back, use json.load(f). The result is a Python list with the same values and types. JSON supports nested structures, so you can store a list of dictionaries or a list of lists. It is the standard for web APIs and configuration files. One caveat: JSON cannot store Python-specific objects like datetime or set directly—you need to convert them to strings or use a custom encoder.

Writing to CSV

CSV is for tabular data—a list of rows, where each row is a list or dictionary. The csv module writes each row with a delimiter (usually a comma). For a list of lists:

import csv
rows = [['name', 'age'], ['Alice', 30], ['Bob', 25]]
with open('output.csv', 'w', newline='') as f:
    writer = csv.writer(f)
    writer.writerows(rows)

If you have a list of dictionaries, use csv.DictWriter and specify fieldnames. Reading CSV back with csv.reader returns strings, so you must manually convert numbers if needed. CSV is the right choice when you plan to open the file in Excel, Google Sheets, or a database. Note that CSV has no standard for encoding special characters or newlines within a field, though the csv module handles quoting automatically.

How to Choose the Right Format

The decision depends on three questions:

• What is the data structure? If it is a flat list of strings or numbers, any format works. If it is nested or contains mixed types, JSON is safest.
• Who will consume the file? Another Python program? JSON or text. A spreadsheet user? CSV. A web service? JSON.
• Do you need to preserve types? JSON preserves int, float, bool, None, and nested structures. CSV and text lose type information.

For example, a list of coordinates [(1.2, 3.4), (5.6, 7.8)] is better as JSON because each tuple can be a list, and the numbers stay floats. If you save it as CSV, you might write each coordinate pair as two columns, which is also fine, but you lose the tuple structure unless you re-assemble it.

Common Mistakes and How to Avoid Them

One frequent error is forgetting to close the file. Using with avoids this. Another is mixing up modes: 'w' overwrites, 'a' appends. For CSV, forgetting newline='' can cause extra blank lines on Windows. When writing JSON, ensure the data is serializable—a set or datetime will raise a TypeError. Also, CSV writes everything as strings, so if you need to preserve numbers, you must convert them back after reading. Finally, be careful with encoding: use encoding='utf-8' when opening files to handle non-ASCII characters.

Performance and File Size Considerations

For large lists, writing to text or CSV is generally faster than JSON because JSON adds structural characters (brackets, commas, quotes). However, JSON files can be more compact for nested data because they avoid repeating headers. If you are dealing with millions of items, consider using json.dump with separators=(',', ':') to reduce size, or use a binary format like pickle for Python-only data. But note that pickle is not safe for untrusted data and is not interoperable with other languages. For CSV, the csv.writer streams row by row, so memory usage is low even for huge files.

Frequently Asked Questions

Can I write a list of integers to a CSV file without quotes?

Yes, the csv.writer will write numbers as plain numbers if you pass them as integers or floats. It only quotes fields that contain the delimiter, newline, or quote character. For example, csv.writer(f).writerow([1, 2, 3]) writes 1,2,3 without quotes.

How do I append a list to an existing JSON file?

JSON does not support appending directly. You need to read the file, load the list, append the new item, and write it back. For example:

with open('data.json', 'r') as f:
    data = json.load(f)
data.append(new_item)
with open('data.json', 'w') as f:
    json.dump(data, f)

This rewrites the whole file, which is fine for small lists.

What is the difference between json.dump and json.dumps?

json.dump writes directly to a file object, while json.dumps returns a JSON string. Use dump when you have a file handle, and dumps when you need the string for something else, like sending over a network.

Why does my CSV file have blank lines between rows?

This happens on Windows when you open the file without newline=''. The csv module writes its own line endings, and the default newline translation adds extra ones. Always open CSV files with newline=''.

Is JSON always better than text for storing a list?

Not always. If the list is simple and you only need to read it as a human, text is fine. If you need to load it back into Python, JSON is safer and more reliable than parsing text manually. JSON also handles Unicode and nested structures better.

Can I write a list of dictionaries to CSV?

Yes, use csv.DictWriter. You must provide fieldnames that match the keys in your dictionaries. Any missing keys will be written as empty strings, and extra keys will be ignored unless you specify extrasaction='ignore'.

Related

• Cloud Storage vs File Sync: Editing on Multiple Devices
• Delete All Steam Cloud Saves? What Actually Happens
• Excel File Disappeared on Mac? Fixes That Work