Skip to main content

How to Read a CSV File from a Zip File with pandas

· 5 min read
Jagdish Kumawat
Founder @ Dewiride

Datasets often come as a zip file with one CSV file inside. You don't need to unzip it first, or open it with Python's zipfile module: pandas.read_csv("archive.zip") reads the CSV straight out of the zip. This guide shows it, and what happens when the zip holds more than one file, with real output from pandas 3.1.1.

Syntax​

Syntax
frame = pd.read_csv(path)
frame = pd.read_csv(path, compression="zip")
PartWhat it means
pathThe zip file. It must hold exactly one file, the CSV
compressionHow the file is compressed. The default, "infer", reads it from the name: a path ending in .zip is unzipped. Pass "zip" when the name doesn't end in .zip

The pandas reference says it in one sentence: "If using 'zip' or 'tar', the ZIP file must contain only one data file to be read in."

Step 1: Make a Zip with One CSV File​

The example is a zip of three orders. If you have no zip at hand, this script makes one, orders.zip, holding orders.csv:

make_zip.py
import zipfile

with zipfile.ZipFile("orders.zip", "w", zipfile.ZIP_DEFLATED) as archive:
archive.writestr("orders.csv", "order,amount,paid\n1001,25.50,True\n1002,12.00,False\n1003,40.25,True\n")
Terminal
uv run python make_zip.py

It prints nothing; orders.zip is now in the folder.

Step 2: Read the CSV Straight from the Zip​

Pass the zip's path to read_csv as if it were the CSV:

The read_zip_csv.py script in a macOS-style code window: it imports pandas, reads orders.zip with pd.read_csv and prints the table and its column types.

read_zip_csv.py
import pandas as pd

orders = pd.read_csv("orders.zip")
print(orders)
print(orders.dtypes)
Terminal
uv run python read_zip_csv.py
Output
order amount paid
0 1001 25.50 True
1 1002 12.00 False
2 1003 40.25 True
order int64
amount float64
paid bool
dtype: object

The output of read_zip_csv.py in a terminal: a table of the three orders with their amounts and a paid column of True and False, then the column types int64, float64 and bool.

pandas saw the .zip ending, unzipped the one file inside and read it like any CSV, column types included: True and False became a bool column.

Step 3: See What Happens with Two Files​

A zip with a second CSV inside, two-files.zip, can't be read this way:

read_two_file_zip.py
import pandas as pd

pd.read_csv("two-files.zip")
Terminal
uv run python read_two_file_zip.py
Output (last line)
ValueError: Multiple files found in ZIP file. Only one file per ZIP: ['orders.csv', 'refunds.csv']

The end of the error in a terminal: ValueError: Multiple files found in ZIP file. Only one file per ZIP, followed by the two names orders.csv and refunds.csv.

The message lists the files, so you know what's inside. For a zip like that, open the zip with Python's zipfile module and hand pandas the one file you want, as How to Read a File Inside a Zip Archive in Python shows.

Common Mistakes​

MistakeWhat happensDo this instead
Extracting the zip to disk firstAn extra file to keep and clean upPass the zip to read_csv
Reading a zip with several filesValueError: Multiple files found in ZIP fileOpen it with zipfile and pick the file
A zip whose name doesn't end in .zippandas reads the compressed bytes as text and fails: UnicodeDecodeError: 'utf-8' codec can't decode byte 0xb0 in position 14: invalid start bytecompression="zip"

Troubleshooting​

SymptomLikely causeFix
ValueError: Multiple files found in ZIP file. Only one file per ZIP: [...]More than one file insideRead one file with zipfile
UnicodeDecodeError: 'utf-8' codec can't decode byte ...The zip's name doesn't end in .zip, so pandas didn't unzip itpd.read_csv(path, compression="zip")

FAQ​

Do the other read_csv options still work?​

Yes. The zip only changes how pandas gets the bytes; sep, dtype, usecols and the rest apply to the CSV inside.

Does it work for other compressed formats?​

The reference lists .gz, .bz2, .zip, .xz, .zst and the .tar variants for compression="infer".

Conclusion​

pd.read_csv("orders.zip") read the three orders straight out of the zip, with the right column types, because the zip held one file. With two files inside, pandas stopped and listed them; for those, pick the file with zipfile.

Additional Resources​