DataFrame객체를 파일로 저장하기-csv-excel-json

pandas Data 저장 튜토리얼 (CSV / Excel / JSON)

https://datascienceparichay.com/article/pandas-save-dataframe-to-an-excel-file/

0. 개요: pandas는 다양한 포맷으로 저장 가능

pandas는 텍스트·스프레드시트·이진·열지향·데이터베이스 등의

여러 형식으로 데이터를 저장할 수 있음 (저장보다 export라는 용어가 보다 애용됨).

메서드	포맷/용도	특징
to_csv	CSV (텍스트)	가장 범용, Excel·타 프로그래밍 언어와 호환 쉬움
to_excel	XLSX (스프레드시트)	보고서/공유용, 여러 시트 가능
to_json	JSON	웹·API·네트워크 전송에 적합
to_parquet	Parquet	대용량·고성능 분석(Spark, Hadoop)
to_pickle	Python 전용 바이너리	Python 전용
to_sql	관계형 DB	직접 테이블로 저장/적재

 

이 문서에서는 CSV / Excel / JSON을 간단히 살펴본다.

pandas 자체에는 PDF로 직접 저장하는 기능은 없음
PDF 저장은 ReportLab 를 통해 DataFrame객체를 저장하거나,
to_html() 을 통해 HTML 로 변경후
weasyprint 모듈의 HTML객체로 만들고 write_pdf()메서드를 호출하여 변환한다.

---

1. 공통 준비: 예제 DataFrame

import pandas as pd
from datetime import datetime

df = pd.DataFrame(
    {
        "name": ["Alice", "Bob", "홍길동"],
        "age": [27, 35, None],                # 결측치 포함
        "score": [91.5, 88.0, 73.25],
        "joined_at": [
            datetime(2023, 5, 1, 9, 30),
            datetime(2024, 1, 15, 14, 5),
            datetime(2025, 9, 1, 8, 0),
        ],
        "dept": pd.Categorical(["R&D", "Sales", "R&D"]),
    }
)

 

관련 ipynb

https://gist.github.com/dsaint31x/f5ecf3246bfee30eb7da1652d6d41da9

pandas_to_csv_to_json_to_excel.ipynb

---

2. CSV 저장 (to_csv)

2.1. 기본 사용

df.to_csv(
    "data.csv", 
    index=False, 
    encoding="utf-8-sig", #Windows 와 호환성 극대화
                          #UTF-8로 저장하되, 파일 맨 앞에 BOM을 추가
)

• Windows Excel의 경우, BOM(Byte Order Mask)가 파일 맨 앞에 없는 utf-8 CSV를 읽을 때 한글이 자주 깨짐.
• utf-8-sig는 파일 맨앞에 BOM (utf-8의 BOM 값은 EF BB BF)이 존재하며 이 경우 한글이 정상적으로 보임.
• Linux나  macOS에선 utf-8 과 utf-8-sig가 차이 없음 (sig는 signature의 약자로 BOM이 utf-8임을 나타낸다는 의미).

좀더 복잡한 형태:

df.to_csv(
    "data.tsv.gz",
    sep="\t",
    index=False,
    encoding="utf-8-sig",
    na_rep="NA",
    float_format="%.2f",
    date_format="%Y-%m-%d %H:%M:%S",
    compression="gzip",
)

---

2.2. 주요 파라미터

• index:
  • row index를 저장할지 여부(기본 True).
  • 보고서 또는 데이터 교환용이면 False 권장
• encoding:
  • 윈도우/엑셀 열람을 고려하면 "utf-8-sig" 추천.
• sep:
  • 구분자(기본 comma ,).
  • TSV면 sep="\t"
• na_rep:
  • 결측치(Not Available) 표기 문자열
• float_format:
  • 부동소수점 표시 형식
  • "%.2f"
• date_format:
  • 날짜 시간 포맷
  • "%Y-%m-%d %H:%M:%S"
• quoting:
  • 따옴표 처리
    • csv.QUOTE_MINIMAL (기본): 필요한 경우만 따옴표(") 사용
    • csv.QUOTE_ALL: 모든 필드에 따옴표 사용
    • csv.QUOTE_NONNUMERIC: 숫자가 아닌 값만 따옴표
    • csv.QUOTE_NONE: 절대 따옴표 안 씀 (주의: 오류 가능)
  • 필드에 구분자/개행 포함 시 중요
• compression:
  • 압축
  • "zip", "gzip", "bz2", "xz" 등
• mode: 파일 쓰기 모드
  • "w" 덮어쓰기
  • "a" 이어쓰기

---

2.3. 파라메터 지정 효과 비교

설정	코드	결과 예시
기본	to_csv("a.csv", index=False)	홍길동,,73.25,2025-09-01 08:00:00
결측치	na_rep="NA"	홍길동,NA,73.25,2025-09-01 08:00:00
소수점	float_format="%.2f"	Alice,27,91.50,2023-05-01 09:30:00
날짜포맷	date_format="%Y/%m/%d %H:%M"	Bob,35,88.00,2024/01/15 14:05
따옴표 처리	quoting=1 (csv.QUOTE_ALL)	모든 필드를 "..."로 감쌈 "Alice","27","91.5","2023-05-01 09:30:00"
압축	compression="gzip"	gzip 파일로 저장

---

3. Excel 저장 (to_excel)

3.1. 기본 사용

df.to_excel(
    "data.xlsx", 
    index=False, 
    engine="openpyxl", # 생략가능.
)

---

3.2. 주요 파라미터

• index:
  • 인덱스 저장 여부
  • 기본 True
• sheet_name:
  • 시트 이름
  • 기본 "Sheet1"
• engine:
  • 보통 "openpyxl" 권장
• na_rep:
  • 결측치 표기 문자열
• float_format:
  • 표시용 숫자 포맷 문자열
  • 주의: Excel 내부에는 실제 숫자 값 그대로 저장되고, 표시 형식은 Excel 프로그램에서 서식을 지정해야 원하는 형태로 보임.  

참고:

to_excel은 데이터를 “값” 그대로 저장하는 역할만 하고, 시각적 포맷팅(숫자 자리수, 날짜 표시 형식 등)은 Excel 프로그램의 서식 기능을 통해 제어함.

---

3.3. 날짜/시간 주의

Excel은 날짜/시간을 시리얼 숫자(1900-01-01 이후 일수 기반, 시간은 하루의 분수)로 저장하고,

보이는 형태는 서식기능을 사용함.

 

보이는 형태까지 조절해서 저장하려면

• 때문에, 아예 문자열로 저장하던지
  
  • 장점: 표시 형태가 파일에 고정됨(환경/지역설정 영향 최소화)
  • 단점: 텍스트라서 Excel의 날짜 계산/피벗에서 날짜로 인식되지 않음
• openpyxl 을 통해 저장된 excel의 해당 셀 서식을 변경해야 한다.
  
  • 장점: 값은 진짜 날짜라서 정렬/계산/피벗 등에 사용 가능
  • 단점: 표시 형식은 서식에 의존(다른 도구로 열면 보이는 형태가 달라질 수 있음)

# (A) pandas가 날짜를 문자열로 써주길 원할 때
import pandas as pd

df2 = df.copy()
# joined_at이 datetime 열이라고 가정
df2["joined_at"] = df2["joined_at"].dt.strftime("%Y-%m-%d %H:%M:%S")

# 문자열로 바뀐 상태 그대로 저장 → Excel에서 텍스트로 보임
df2.to_excel(
    "excel_dates_as_text.xlsx",
    index=False,
    engine="openpyxl",  # 생략 가능
)

# (B) 숫자로 날짜를 저장한 뒤 Excel에서 서식 지정(Python 코드로도 제어가능)
import pandas as pd
from openpyxl.styles import numbers

# 1) 먼저 엑셀에 저장(엑셀 datetime으로 저장됨)
with pd.ExcelWriter("excel_dates_serial.xlsx", engine="openpyxl") as writer:
    df.to_excel(writer, sheet_name="Report", index=False)

    # 2) 워크북/워크시트 객체에 접근해 표시 형식 지정
    ws = writer.book["Report"]

    # joined_at 열이 D열이라고 가정 (헤더는 1행, 데이터는 2행부터)
    for cell in ws["D"][1:]:  # D2, D3, ... (openpyxl은 1-based 행, 슬라이스는 헤더 제외)
        cell.number_format = "hh:mm:ss" # 시간 보이나 실제론 날짜정보도 있음.
                                        # read_excel로 읽어서 확인해 볼 것.

---

4. JSON 저장 (to_json)

2024.01.07 - [분류 전체보기] - [Term] JSON (JavaScript Object Notation) :

[Term] JSON (JavaScript Object Notation) :

4.1. 기본 사용

df.to_json(
    "data.json", 
    orient="records", 
    force_ascii=False, 
    indent=2,
)

---

4.2. 주요 파라미터

• orient: 레코드 배열 방식을 지정.
  • "records"(일반적), "columns", "index", "split", "table" 등
• indent: 들여쓰기
  • 사람이 보기 좋게 공백 들여쓰기
  • 기본 None 이나 indent=2등으로 지정할 수 있음.
• date_format:
  • "iso" : (권장) ISO8601 문자열 로 직렬화(예: "2025-09-26T10:30:00.000Z")
  • "epoch" : (기본) timestamp 숫자 로 직렬화.
• date_unit: epoch 단위.
  • "s", "ms", "us", "ns" 등: 기본 "ms"
  • date_format="epoch" 일 때
• double_precision:
  • 소수점 자릿수
  • 10이 기본.
• compression:
  • "gzip", "zip", "bz2" 등
• lines=True:
  • False 가 기본.
  • JSON Lines(레코드별 한 줄) 생성.
  • indent설정보다 우선권으로 True시 indent설정 무시.
  • 스트리밍/로그 처리에 유용

---

4.3. orient 별 예제

records

[
  {"name":"Alice","age":27,"score":91.5,"joined_at":"2023-05-01 09:30:00"},
  {"name":"Bob","age":35,"score":88.0,"joined_at":"2024-01-15 14:05:00"},
  {"name":"홍길동","age":null,"score":73.25,"joined_at":"2025-09-01 08:00:00"}
]

---

columns

열 중심 딕셔너리

{
  "name":     {"0":"Alice","1":"Bob","2":"홍길동"},
  "age":      {"0":27,"1":35,"2":null},
  "score":    {"0":91.5,"1":88.0,"2":73.25},
  "joined_at":{"0":"2023-05-01 09:30:00","1":"2024-01-15 14:05:00","2":"2025-09-01 08:00:00"}
}

---

index

인덱스 기준 레코드 맵

{
  "0":{"name":"Alice","age":27,"score":91.5,"joined_at":"2023-05-01 09:30:00"},
  "1":{"name":"Bob","age":35,"score":88.0,"joined_at":"2024-01-15 14:05:00"},
  "2":{"name":"홍길동","age":null,"score":73.25,"joined_at":"2025-09-01 08:00:00"}
}

---

split

헤더/인덱스/데이터 분리 — 구조적 교환에 유용

{
  "columns":["name","age","score","joined_at"],
  "index":[0,1,2],
  "data":[
    ["Alice",27,91.5,"2023-05-01 09:30:00"],
    ["Bob",35,88.0,"2024-01-15 14:05:00"],
    ["홍길동",null,73.25,"2025-09-01 08:00:00"]
  ]
}

---

table

메타데이터 포함 — 표준화/스키마 교환에 적합

{
  "schema": {
    "fields": [
      {"name":"index","type":"integer"},
      {"name":"name","type":"string"},
      {"name":"age","type":["number","null"]},
      {"name":"score","type":"number"},
      {"name":"joined_at","type":"string"}
    ],
    "primaryKey":["index"],
    "pandas_version":"0.20.0"
  },
  "data": [
    {"index":0,"name":"Alice","age":27,"score":91.5,"joined_at":"2023-05-01 09:30:00"},
    {"index":1,"name":"Bob","age":35,"score":88.0,"joined_at":"2024-01-15 14:05:00"},
    {"index":2,"name":"홍길동","age":null,"score":73.25,"joined_at":"2025-09-01 08:00:00"}
  ]
}

---

5. 저장 후 읽기 검증

# CSV
df.to_csv("check.csv", index=False, encoding="utf-8-sig")
df_csv = pd.read_csv("check.csv")

# Excel
df.to_excel("check.xlsx", index=False)
df_xlsx = pd.read_excel("check.xlsx")

# JSON (records)
df.to_json("check.json", orient="records", force_ascii=False, indent=2)
df_json = pd.read_json("check.json", orient="records")

---

같이 보면 좋은 자료들

2024.04.13 - [Python/pandas] - [DL] Pandas 로 csv 읽기: read_csv()

[DL] Pandas 로 csv 읽기: read_csv()

2025.09.26 - [Python/pandas] - pandas.read_excel() 함수:

pandas.read_excel() 함수:

 

2025.08.06 - [Python] - Python에서 JSON 다루기-json모듈

Python에서 JSON 다루기-json모듈

2024.01.07 - [개발환경] - [CE] Text file: Text 파일이란?

[CE] Text file: Text 파일이란?

---