Read & Write Files with Polars

Polars is a fast DataFrame library for Python. It handles many file formats with ease. This guide shows you how to read and write CSV, JSON, Parquet, and Excel files. Each example is simple and ready to use.

If you are new to Polars, check out our Install Polars in Python Step by Step guide first. It helps you set up everything quickly.

Reading CSV Files

CSV is the most common data format. Polars reads it with pl.read_csv(). This function is fast and handles large files well. Use it for simple or complex CSV files.

Here is a basic example. We read a file named data.csv with three columns.

import polars as pl

# Read a CSV file
df = pl.read_csv("data.csv")
print(df)

Output:

shape: (3, 3)
┌─────┬──────┬─────┐
│ id  ┆ name ┆ age │
│ --- ┆ ---  ┆ --- │
│ i64 ┆ str  ┆ i64 │
╞═════╪══════╪═════╡
│ 1   ┆ Alex ┆ 25  │
│ 2   ┆ Sam  ┆ 30  │
│ 3   ┆ Jia  ┆ 22  │
└─────┴──────┴─────┘

You can also specify data types. Use the dtypes parameter. This helps when columns have mixed types.

# Read CSV with explicit types
df = pl.read_csv("data.csv", dtypes={"age": pl.Int32})
print(df.dtypes)

Output:

[Int64, String, Int32]

Writing CSV Files

Writing CSV is just as easy. Use the write_csv() method. It saves your DataFrame to a file. You can set options like separator or include header.

# Write DataFrame to CSV
df.write_csv("output.csv")
print("File saved as output.csv")

Output:

File saved as output.csv

To change the separator, use the sep parameter. For example, use a semicolon for European formats.

# Write CSV with semicolon separator
df.write_csv("output_eu.csv", sep=";")

Reading JSON Files

Polars reads JSON files with pl.read_json(). It works with standard JSON arrays. Each object becomes a row. This is great for API data.

# Read a JSON file
df_json = pl.read_json("data.json")
print(df_json)

Output:

shape: (3, 3)
┌─────┬──────┬─────┐
│ id  ┆ name ┆ age │
│ --- ┆ ---  ┆ --- │
│ i64 ┆ str  ┆ i64 │
╞═════╪══════╪═════╡
│ 1   ┆ Alex ┆ 25  │
│ 2   ┆ Sam  ┆ 30  │
│ 3   ┆ Jia  ┆ 22  │
└─────┴──────┴─────┘

If your JSON is nested, use the json_path parameter. It extracts a specific path. This helps with complex structures.

# Read JSON with a path
df_nested = pl.read_json("nested.json", json_path="$.data")
print(df_nested)

Output:

shape: (2, 2)
┌─────┬──────┐
│ id  ┆ name │
│ --- ┆ ---  │
│ i64 ┆ str  │
╞═════╪══════╡
│ 1   ┆ Bob  │
│ 2   ┆ Eve  │
└─────┴──────┘

Writing JSON Files

Use the write_json() method to save DataFrames as JSON. It creates a clean array of objects.

# Write DataFrame to JSON
df.write_json("output.json")
print("File saved as output.json")

Output:

File saved as output.json

You can also write to a string. Use write_json() without a file path.

# Get JSON string
json_str = df.write_json()
print(json_str[:50])

Output:

[{"id":1,"name":"Alex","age":25},{"id":2,...

Reading Parquet Files

Parquet is a columnar storage format. It is fast and compressed. Polars reads it with pl.read_parquet(). This is ideal for big data pipelines.

# Read a Parquet file
df_parquet = pl.read_parquet("data.parquet")
print(df_parquet)

Output:

shape: (3, 3)
┌─────┬──────┬─────┐
│ id  ┆ name ┆ age │
│ --- ┆ ---  ┆ --- │
│ i64 ┆ str  ┆ i64 │
╞═════╪══════╪═════╡
│ 1   ┆ Alex ┆ 25  │
│ 2   ┆ Sam  ┆ 30  │
│ 3   ┆ Jia  ┆ 22  │
└─────┴──────┴─────┘

Parquet supports predicates. Use the columns parameter to read only specific columns. This reduces memory usage.

# Read only two columns from Parquet
df_subset = pl.read_parquet("data.parquet", columns=["name", "age"])
print(df_subset)

Output:

shape: (3, 2)
┌──────┬─────┐
│ name ┆ age │
│ ---  ┆ --- │
│ str  ┆ i64 │
╞══════╪═════╡
│ Alex ┆ 25  │
│ Sam  ┆ 30  │
│ Jia  ┆ 22  │
└──────┴─────┘

Writing Parquet Files

Use the write_parquet() method. It compresses data by default. This saves disk space and speeds up future reads.

# Write DataFrame to Parquet
df.write_parquet("output.parquet")
print("File saved as output.parquet")

Output:

File saved as output.parquet

You can change compression. Use the compression parameter. Options include snappy, gzip, or lz4.

# Write with gzip compression
df.write_parquet("output_gzip.parquet", compression="gzip")

Reading Excel Files

Polars supports Excel files with the read_excel() function. You need the openpyxl or xlrd library installed. Install it with pip install openpyxl.

# Read an Excel file
df_excel = pl.read_excel("data.xlsx")
print(df_excel)

Output:

shape: (3, 3)
┌─────┬──────┬─────┐
│ id  ┆ name ┆ age │
│ --- ┆ ---  ┆ --- │
│ i64 ┆ str  ┆ i64 │
╞═════╪══════╪═════╡
│ 1   ┆ Alex ┆ 25  │
│ 2   ┆ Sam  ┆ 30  │
│ 3   ┆ Jia  ┆ 22  │
└─────┴──────┴─────┘

You can read a specific sheet. Use the sheet_name parameter. This is useful for multi-sheet workbooks.

# Read a specific sheet
df_sheet = pl.read_excel("data.xlsx", sheet_name="Sheet2")
print(df_sheet)

Output:

shape: (2, 2)
┌──────┬────────┐
│ city ┆ sales  │
│ ---  ┆ ---    │
│ str  ┆ f64    │
╞══════╪════════╡
│ NYC  ┆ 100.5  │
│ LA   ┆ 200.3  │
└──────┴────────┘

Writing Excel Files

Use the write_excel() method. It creates an Excel file with one sheet. You can add multiple sheets by passing a dictionary.

# Write DataFrame to Excel
df.write_excel("output.xlsx")
print("File saved as output.xlsx")

Output:

File saved as output.xlsx

To write multiple sheets, use a dictionary of DataFrames.

# Write multiple sheets
dfs = {"Sheet1": df, "Sheet2": df_sheet}
pl.write_excel(dfs, "multi_sheet.xlsx")

Performance Tips

Polars is built for speed. Use Parquet for large datasets. It reads and writes faster than CSV. Use JSON for web data. Use Excel for reports.

Always specify data types when reading CSV. This avoids type inference delays. For Parquet, use column selection to reduce memory.

If you want to understand Polars better, read our Polars DataFrames and Series Guide. It explains core concepts in detail.

For a comparison with Pandas, see Polars vs Pandas: Why Switch?. It helps you decide which tool fits your workflow.

Conclusion

Polars makes file I/O simple and fast. You can read and write CSV, JSON, Parquet, and Excel with just a few lines of code. Each format has its strengths. Choose the one that fits your data size and use case. Practice with the examples above. You will soon handle any file format with confidence.