Python'da JSON'dan CSV'ye — DictWriter + pandas Örnekleri
Ücretsiz JSON'dan CSV'ye Dönüştürücü aracını doğrudan tarayıcınızda kullanın — kurulum gerektirmez.
JSON'dan CSV'ye Dönüştürücü Online Dene →Neredeyse her veri işlem hattı eninde sonunda aynı adımla karşılaşır: bir API JSON döndürür, ancak sonraki tüketici — elektronik tablo, içe aktarma betiği, Redshift COPY komutu — CSV ihtiyacı duyar. İç içe nesneler, tutarsız anahtarlar veya özel işlem gerektiren tarih-saat değerleriyle karşılaşana kadar Python'da JSON'u CSV'ye dönüştürmek önemsiz görünür. Python size iki sağlam yol sunar: sıfır bağımlılıklı betikler için yerleşik json + csv modülleri ve iç içe düzleştirme ile daha büyük veri kümeleri için pandas — ya da herhangi bir kod gerektirmeden hızlı tek seferlik dönüşümler için çevrimiçi JSON to CSV dönüştürücüsü. Bu kılavuz, çalıştırılabilir Python 3.8+ örnekleriyle her iki yaklaşımı baştan sona kapsar.
- ✓csv.DictWriter, sıfır bağımlılıkla sözlük listesini CSV'ye dönüştürür — ayrıştırmak için json.load(), ardından writeheader() + writerows() kullanın.
- ✓Windows'ta veri satırları arasında boş satırları önlemek için CSV dosyalarını her zaman newline="" ile açın.
- ✓pd.json_normalize(), to_csv() çağrısından önce iç içe JSON'u düz bir DataFrame'e düzleştirir — çok düzeyli iç içe yapıları otomatik olarak ele alır.
- ✓DataFrame.to_csv() fonksiyonuna index=False geçirin — aksi hâlde pandas istenmeyen satır numarası sütunu yazar.
- ✓500 MB'ın üzerindeki dosyalar için sabit bellek kullanımı için csv.DictWriter ile birlikte ijson akış JSON ayrıştırmasını kullanın.
JSON'dan CSV'ye Dönüşüm Nedir?
JSON'dan CSV'ye dönüşüm, bir JSON nesne dizisini her nesnenin bir satır, her anahtarın bir sütun başlığı olduğu tablo biçimine dönüştürür. JSON hiyerarşiktir — nesneler keyfi derinlikte iç içe olabilir. CSV düzdür — her değer bir satır-sütun ızgarasında bulunur. Her nesne aynı üst düzey anahtar kümesini paylaştığında dönüşüm temiz çalışır. İç içe nesneler, diziler ve tutarsız anahtarlar ilginç hâle geldiği yerdir. Ham veriler aynı kalır; yalnızca yapı değişir.
[{"order_id":"ord_91a3","total":149.99,"status":"shipped"},
{"order_id":"ord_b7f2","total":34.50,"status":"pending"}]order_id,total,status ord_91a3,149.99,shipped ord_b7f2,34.50,pending
csv.DictWriter — pandas Olmadan JSON'u CSV'ye Dönüştürme
csv modülü her Python kurulumunda gelir. pip install yok, sanal ortam uğraşı yok. csv.DictWriter bir sözlük listesi alır ve her birini sözlük anahtarlarını sütun başlıklarına eşleyerek CSV satırı olarak yazar. fieldnames parametresi hem sütun sırasını hem de hangi anahtarların dahil edileceğini denetler.
import json
import csv
# Örnek JSON verisi — sipariş nesneleri dizisi
json_string = """
[
{"order_id": "ord_91a3", "product": "Wireless Keyboard", "quantity": 2, "unit_price": 74.99},
{"order_id": "ord_b7f2", "product": "USB-C Hub", "quantity": 1, "unit_price": 34.50},
{"order_id": "ord_c4e8", "product": "Monitor Stand", "quantity": 3, "unit_price": 29.95}
]
"""
records = json.loads(json_string)
with open("orders.csv", "w", newline="", encoding="utf-8") as csvfile:
writer = csv.DictWriter(csvfile, fieldnames=records[0].keys())
writer.writeheader()
writer.writerows(records)
# orders.csv:
# order_id,product,quantity,unit_price
# ord_91a3,Wireless Keyboard,2,74.99
# ord_b7f2,USB-C Hub,1,34.50
# ord_c4e8,Monitor Stand,3,29.95open() üzerindeki bu newline="" argümanı Windows'ta isteğe bağlı değildir. Olmadan, çift satır başı alırsınız — Excel'de her veri satırı arasında boş satır olarak görünür. macOS ve Linux'ta zararsızdır, bu yüzden her zaman ekleyin.
Yukarıdaki kod bir dize için json.loads() kullanır. Dosya tutamacından okurken json.load() (sondaki s olmadan) kullanın. Bu sürekli insanları şaşırtır — biri dizeyi, diğeri dosya nesnesini okur.
import json
import csv
with open("server_metrics.json", encoding="utf-8") as jf:
metrics = json.load(jf) # dosya nesneleri için json.load()
# Açık fieldnames sütun sırasını denetler
columns = ["timestamp", "hostname", "cpu_percent", "memory_mb", "disk_io_ops"]
with open("server_metrics.csv", "w", newline="", encoding="utf-8") as cf:
writer = csv.DictWriter(cf, fieldnames=columns, extrasaction="ignore")
writer.writeheader()
writer.writerows(metrics)
# Yalnızca belirtilen beş sütun, tam olarak bu sırayla görünürextrasaction="ignore" ayarı, fieldnames listenizde olmayan sözlüklerdeki anahtarları sessizce atar. Varsayılan "raise"'dir, herhangi bir sözlükte beklenmedik bir anahtar varsa ValueError fırlatır. Sürprizlere toleransınıza hangisi uyuyorsa onu seçin.
csv.DictWriter ile csv.writer karşılaştırması: DictWriter sözlük anahtarlarını otomatik olarak sütun konumlarına eşler. csv.writer ham listeleri satır olarak yazar — sütun sıralamasını kendiniz yönetirsiniz. JSON kayıtları zaten sözlük olduğundan DictWriter, JSON'dan CSV'ye dönüşüm için neredeyse her zaman doğru seçimdir.Python'un csv modülü üç adlandırılmış lehçeyle gelir: excel (virgül sınırlayıcı, CRLF satır sonları — varsayılan), excel-tab (sekme sınırlayıcı, CRLF sonları) ve unix (LF satır sonları, sayısal olmayan tüm alanları tırnak içine alır). Lehçe adını csv.DictWriter'a dialect argümanı olarak geçirin. Hedef sisteminizin olağandışı tırnaklama veya sınırlayıcı kuralları varsa csv.register_dialect() ile özel bir lehçe de tanımlayabilirsiniz. Çoğu JSON'dan CSV'ye iş akışı için excel lehçesi doğrudur, ancak awk veya sort gibi POSIX araçlarıyla işlenecek dosyalar yazarken unix'e geçin.
Standart Dışı Tipleri Ele Alma: datetime, UUID ve Decimal
API'lerden gelen JSON genellikle tarihleri ISO dizeleri, UUID'leri kısa çizgili dizeler ve parasal değerleri float olarak içerir. Bunları CSV yazmadan önce işlemek amacıyla Python nesnelerine ayrıştırdığınızda tekrar dizelere dönüştürmeniz gerekir. csv modülü her değerde str() çağırır, bu nedenle çoğu tip çalışır. Ancak datetime nesneleri dağınık varsayılan dize gösterimleri üretir ve Decimal değerleri bilimsel gösterimi önlemek için açık biçimlendirme gerektirir.
import json
import csv
from datetime import datetime, timezone
from decimal import Decimal
from uuid import UUID
# Python tipleriyle ayrıştırılmış API yanıtını simüle etme
transactions = [
{
"txn_id": UUID("a1b2c3d4-e5f6-7890-abcd-ef1234567890"),
"created_at": datetime(2026, 3, 15, 9, 30, 0, tzinfo=timezone.utc),
"amount": Decimal("1249.99"),
"currency": "USD",
"merchant": "CloudHost Inc.",
},
{
"txn_id": UUID("b2c3d4e5-f6a7-8901-bcde-f12345678901"),
"created_at": datetime(2026, 3, 15, 14, 12, 0, tzinfo=timezone.utc),
"amount": Decimal("87.50"),
"currency": "EUR",
"merchant": "DataSync GmbH",
},
]
def prepare_row(record: dict) -> dict:
"""Dize olmayan tipleri CSV uyumlu dizelere dönüştür."""
return {
"txn_id": str(record["txn_id"]),
"created_at": record["created_at"].isoformat(),
"amount": f"{record['amount']:.2f}",
"currency": record["currency"],
"merchant": record["merchant"],
}
with open("transactions.csv", "w", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=["txn_id", "created_at", "amount", "currency", "merchant"])
writer.writeheader()
for txn in transactions:
writer.writerow(prepare_row(txn))
# transactions.csv:
# txn_id,created_at,amount,currency,merchant
# a1b2c3d4-e5f6-7890-abcd-ef1234567890,2026-03-15T09:30:00+00:00,1249.99,USD,CloudHost Inc.
# b2c3d4e5-f6a7-8901-bcde-f12345678901,2026-03-15T14:12:00+00:00,87.50,EUR,DataSync GmbHprepare_row() fonksiyonu burada doğru yaklaşımdır. csv.DictWriter'a özel tipler öğretmeye çalışmak yerine yazmadan önce her kaydı dizelere normalleştirirsiniz. datetime nesnelerinde str()'a güvenmek yerine .isoformat() çağrısını tercih ederim — çıktı biçimi daha öngörülüdür ve alt akış ayrıştırıcıları ISO 8601'i güvenilir biçimde ele alır.
Decimal değerlerini biçimlendirmeden geçirirseniz, çok küçük veya çok büyük sayılar bilimsel gösterimde oluşabilir (örneğin 1.5E+7). CSV'ye finansal veri yazarken her zaman f"{value:.2f}" gibi açık bir f-dizesiyle Decimal'i biçimlendirin.Çok sayıda özel tipin bulunduğu işlem hatları için alternatif bir kalıp json.JSONEncoder'ı genişletmektir. Alt sınıf oluşturun, default() metodunu geçersiz kılarak her özel tip için JSON serileştirilebilir bir değer döndürün, ardından alt sınıfı json.dumps()'a cls argümanı olarak geçirin. CSV'ye yazmadan önce özel kodlayıcı aracılığıyla yeniden kodlamak, satır başına prepare_row() çağrısı olmadan tüm tipleri tek adımda normalleştirir. Yukarıda gösterilen prepare_row() kalıbı tek seferlik betikler için daha basittir; JSONEncoder alt sınıfı yaklaşımı ise özel tiplerle aynı etki alanı modeli birçok işlem hattı aşaması veya mikro hizmet arasında paylaşıldığında daha iyi ölçeklenir.
csv.DictWriter Parametre Başvurusu
Tam kurucu imzası csv.DictWriter(f, fieldnames, restval="", extrasaction="raise", dialect="excel", **fmtparams)'dır. Bunların çoğunun makul varsayılanları vardır. Gerçekten değiştireceğiniz parametreler fieldnames, delimiter ve extrasaction'dır.
pandas — DataFrame'lerle JSON'u CSV'ye Dönüştürme
Zaten pandas ağırlıklı bir kod tabanında çalışıyorsanız veya JSON'unuzda düzleştirmeniz gereken iç içe nesneler varsa, pandas yaklaşımı stdlib sürümünden önemli ölçüde daha az kod gerektirir. Takas: pandas ~30 MB'lık bir bağımlılıktır. Tek kullanımlık bir betik için bu iyidir. Üretime gönderdiğiniz bir Docker imajı için stdlib yaklaşımı işleri daha hafif tutar.
import pandas as pd
# JSON dizisini doğrudan bir DataFrame'e oku
df = pd.read_json("warehouse_inventory.json")
# CSV'ye yaz — index=False otomatik oluşturulan satır numaralarını önler
df.to_csv("warehouse_inventory.csv", index=False)
# Hepsi bu kadar. İki satır. pandas sütun tiplerini otomatik olarak çıkarır.index=False bayrağı her seferinde bakıp aradığınız şeylerden biridir. Olmadan pandas CSV'nizin ilk sütunu olarak bir 0, 1, 2, ... sütunu yazar. Kimse bunu istemez.
json_normalize ile İç İçe JSON'u Düzleştirme
Gerçek API yanıtları nadiren düzdür. Siparişler teslimat adresleri içerir, kullanıcılar iç içe tercihler içerir, telemetri olayları iç içe meta veriler içerir. pd.json_normalize() iç içe sözlüklerde yürür ve onları nokta ayrılmış adlarla sütunlara düzleştirir.
import json
import pandas as pd
api_response = """
[
{
"order_id": "ord_91a3",
"placed_at": "2026-03-15T09:30:00Z",
"customer": {
"name": "Sarah Chen",
"email": "s.chen@example.com",
"tier": "premium"
},
"shipping": {
"method": "express",
"address": {
"city": "Portland",
"state": "OR",
"zip": "97201"
}
},
"total": 299.95
},
{
"order_id": "ord_b7f2",
"placed_at": "2026-03-15T14:12:00Z",
"customer": {
"name": "James Park",
"email": "j.park@example.com",
"tier": "standard"
},
"shipping": {
"method": "standard",
"address": {
"city": "Austin",
"state": "TX",
"zip": "73301"
}
},
"total": 87.50
}
]
"""
orders = json.loads(api_response)
# json_normalize iç içe dict'leri düzleştirir — sep birleştirici karakteri denetler
df = pd.json_normalize(orders, sep="_")
df.to_csv("flat_orders.csv", index=False)
# Elde edilen sütunlar:
# order_id, placed_at, customer_name, customer_email, customer_tier,
# shipping_method, shipping_address_city, shipping_address_state,
# shipping_address_zip, totalsep="_" parametresi iç içe anahtar adlarının nasıl birleştirileceğini denetler. Varsayılan "."'dır ve customer.name gibi sütunlar üretir. Sütun adlarındaki noktalar SQL içe aktarmaları ve bazı elektronik tablo formüllerinde sorun çıkardığından alt çizgileri tercih ederim.
Kayıtlar dizisini iç içe bir anahtar altında saran API yanıtları için record_path parametresini kullanın. Yanıt {"data": {"orders": [...]}} gibi görünüyorsa doğru listeye gitmek için record_path=["data", "orders"] geçirin. İsteğe bağlı meta parametresi iç içe kayıtlarla birlikte üst düzey alanları çekmenizi sağlar — her satırda sütun olarak istediğiniz üst düzey sayfalama bilgisi (sayfa numarası, toplam sayım) yanıtın içerdiği durumlarda kullanışlıdır. record_path ve meta birlikte, özel ön işleme olmadan gerçek dünya iç içe API yanıt şekillerinin çoğunu ele alır.
DataFrame.to_csv() Parametre Başvurusu
DataFrame.to_csv() 20'den fazla parametreye sahiptir. Bunlar JSON'dan CSV'ye iş akışları için önemli olanlardır.
import pandas as pd
df = pd.read_json("telemetry_events.json")
# Açık kodlama ve eksik değer işlemeyle TSV çıktısı
df.to_csv(
"telemetry_events.tsv",
sep="\t",
index=False,
encoding="utf-8",
na_rep="NULL",
columns=["event_id", "timestamp", "source", "severity", "message"],
)
# Kabuk betiklerinde pipe için stdout'a yaz
print(df.to_csv(index=False))
# Dize olarak döndür (dosya yazılmaz)
csv_string = df.to_csv(index=False)
print(len(csv_string), "karakter")Dosya ve API Yanıtından JSON'u CSV'ye Dönüştürme
En yaygın iki gerçek dünya senaryosu: diskteki bir dosyadan JSON okuyup dönüştürmek veya bir HTTP API'sinden JSON çekip sonucu CSV olarak kaydetmek. Geliştirmede hata işleme olmadan geçiştirebilirsiniz. Üretimde bu tercih sabah 2'deki bir uyarıya dönüşür. Dosyalar mevcut olmayabilir, API'ler JSON yerine 4xx veya 5xx durum kodları döndürebilir, yanıt gövdesi dizi yerine hata nesnesi olabilir veya JSON bir ağ zaman aşımı nedeniyle kesik olabilir. Aşağıdaki kalıplar tüm bu durumları açıkça ele alır, hataları stderr'e kaydeder ve arayanların sıfır satırlı çıktıları tespit edip uyarı verebilmesi için satır sayısı döndürür.
Diskteki Dosya — Oku, Dönüştür, Kaydet
import json
import csv
import sys
def json_file_to_csv(input_path: str, output_path: str) -> int:
"""Nesne dizisi içeren JSON dosyasını CSV'ye dönüştür.
Yazılan satır sayısını döndürür.
"""
try:
with open(input_path, encoding="utf-8") as jf:
data = json.load(jf)
except FileNotFoundError:
print(f"Hata: {input_path} bulunamadı", file=sys.stderr)
return 0
except json.JSONDecodeError as exc:
print(f"Hata: {input_path} içinde geçersiz JSON: {exc.msg}, satır {exc.lineno}", file=sys.stderr)
return 0
if not isinstance(data, list) or not data:
print(f"Hata: {input_path} içinde boş olmayan JSON dizisi beklendi", file=sys.stderr)
return 0
# Tutarsız şemaları ele almak için tüm kayıtlardaki benzersiz anahtarları topla
all_keys: list[str] = []
seen: set[str] = set()
for record in data:
for key in record:
if key not in seen:
all_keys.append(key)
seen.add(key)
with open(output_path, "w", newline="", encoding="utf-8") as cf:
writer = csv.DictWriter(cf, fieldnames=all_keys, restval="", extrasaction="ignore")
writer.writeheader()
writer.writerows(data)
return len(data)
rows = json_file_to_csv("deploy_logs.json", "deploy_logs.csv")
print(f"deploy_logs.csv dosyasına {rows} satır yazıldı")HTTP API Yanıtı — Çek ve Dönüştür
import json
import csv
import urllib.request
import urllib.error
def api_response_to_csv(url: str, output_path: str) -> int:
"""Bir REST API uç noktasından JSON çek ve CSV olarak yaz."""
try:
req = urllib.request.Request(url, headers={"Accept": "application/json"})
with urllib.request.urlopen(req, timeout=30) as resp:
if resp.status != 200:
print(f"Hata: API {resp.status} durumu döndürdü")
return 0
body = resp.read().decode("utf-8")
except urllib.error.URLError as exc:
print(f"Hata: {url} adresine ulaşılamadı: {exc.reason}")
return 0
try:
records = json.loads(body)
except json.JSONDecodeError as exc:
print(f"Hata: API geçersiz JSON döndürdü: {exc.msg}")
return 0
if not isinstance(records, list) or not records:
print("Hata: API'den boş olmayan JSON dizisi beklendi")
return 0
with open(output_path, "w", newline="", encoding="utf-8") as cf:
writer = csv.DictWriter(cf, fieldnames=records[0].keys())
writer.writeheader()
writer.writerows(records)
return len(records)
rows = api_response_to_csv(
"https://api.internal.example.com/v2/deployments?status=completed",
"completed_deployments.csv",
)
print(f"{rows} dağıtım CSV'ye aktarıldı")urllib'i kullanır. requests yüklüyse urllib bölümünü resp = requests.get(url, timeout=30); records = resp.json() ile değiştirin — CSV yazma kodunun geri kalanı aynı kalır.Komut Satırından JSON'u CSV'ye Dönüştürme
Bazen terminalde tek satıra ihtiyaç duyarsınız. Python'un -c bayrağı bir betik dosyası oluşturmadan hızlı dönüşüm yapmanızı sağlar. Daha karmaşık dönüşümler için önce verileri yeniden şekillendirmek amacıyla jq üzerinden pipe yapın, ardından dönüştürün.
# Python tek satırı: stdin'den JSON okur, stdout'a CSV yazar cat orders.json | python3 -c " import json, csv, sys data = json.load(sys.stdin) w = csv.DictWriter(sys.stdout, fieldnames=data[0].keys()) w.writeheader() w.writerows(data) " # Çıktıyı dosyaya kaydet cat orders.json | python3 -c " import json, csv, sys data = json.load(sys.stdin) w = csv.DictWriter(sys.stdout, fieldnames=data[0].keys()) w.writeheader() w.writerows(data) " > orders.csv
# json2csv.py olarak kaydedin ve şöyle çalıştırın: python3 json2csv.py input.json -o output.csv
python3 -c "
import json, csv, argparse, sys
parser = argparse.ArgumentParser(description='Convert JSON array to CSV')
parser.add_argument('input', help='Path to JSON file')
parser.add_argument('-o', '--output', default=None, help='Output CSV path (default: stdout)')
parser.add_argument('-d', '--delimiter', default=',', help='CSV delimiter')
args = parser.parse_args()
with open(args.input) as f:
data = json.load(f)
out = open(args.output, 'w', newline='') if args.output else sys.stdout
writer = csv.DictWriter(out, fieldnames=data[0].keys(), delimiter=args.delimiter)
writer.writeheader()
writer.writerows(data)
if args.output:
out.close()
print(f'Wrote {len(data)} rows to {args.output}', file=sys.stderr)
" "$@"# csvkit kurulumu: pip install csvkit
# jq alanları düzleştirir ve seçer, in2csv CSV biçimlendirmeyi yapar
cat api_response.json | jq '[.[] | {id: .order_id, customer: .customer.name, total}]' | in2csv -f json > orders.csv
# Miller (mlr) JSON'dan CSV'ye için başka bir seçenektir
mlr --json2csv cat orders.json > orders.csvMiller (mlr), Python çalışma zamanı gerektirmeden JSON, CSV ve TSV'yi birinci sınıf biçimler olarak ele alan bağımsız bir ikili dosyadır. --json2csv bayrağı JSON girişini tek geçişte CSV'ye dönüştürür; aynı komutta çıktı yazmadan önce sütunları filtrelemek, sıralamak veya yeniden adlandırmak için Miller fiillerini zincirleyebilirsiniz. macOS'ta Homebrew üzerinden (brew install miller) veya Linux paket yöneticinizle yükleyin. Python ortamı başlatmadan hızlı JSON'dan CSV'ye dönüşüm istediğiniz CI işlem hatlarında özellikle kullanışlıdır.
Yüksek Performanslı Alternatif — pyarrow ile pandas
Onlarca milyon satır aralığındaki veri kümeleri için pyarrow arka ucuyla pandas, varsayılana kıyasla önemli ölçüde daha hızlı okur ve yazar. C destekli Arrow motoru, Python'un satır satır csv modülünden daha verimli biçimde sütunsal verileri işler. API aynı kalır — yalnızca engine parametresini ayarlarsınız.
pip install pyarrow
import pandas as pd
# pyarrow motoruyla JSON oku (büyük dosyalar için daha hızlı ayrıştırma)
df = pd.read_json("sensor_readings.json", engine="pyarrow")
# to_csv'nin engine parametresi yoktur, ancak okuma ve yazma arasındaki
# DataFrame işlemleri pyarrow'un sütunsal düzeninden yararlanır
df.to_csv("sensor_readings.csv", index=False)
# Gerçekten büyük dışa aktarmalar için CSV yerine Parquet'e yazmayı düşünün
# — ikili biçim, 5-10x daha küçük, tipleri korur
df.to_parquet("sensor_readings.parquet", engine="pyarrow")Birkaç yüz MB'ı aşan JSON işliyorsanız ve son tüketici Parquet kabul ediyorsa CSV'yi tamamen atlayın. Parquet daha küçüktür, sütun tiplerini korur ve hem Redshift hem de BigQuery natively yükler. CSV kayıplı bir biçimdir — her değer dizeye dönüşür.
Sözdizimi Vurgulamayla Terminal Çıktısı
rich kütüphanesi terminalde kenarlıklar, hizalama ve renkle tablolar oluşturur — çıktı dosyasını açmadan geliştirme sırasında dönüşümü önizlemek için kullanışlıdır.
pip install rich
import json
from rich.console import Console
from rich.table import Table
json_string = """
[
{"hostname": "web-prod-1", "cpu_percent": 72.3, "memory_mb": 3840, "uptime_hours": 720},
{"hostname": "web-prod-2", "cpu_percent": 45.1, "memory_mb": 2560, "uptime_hours": 168},
{"hostname": "db-replica-1", "cpu_percent": 91.7, "memory_mb": 7680, "uptime_hours": 2160}
]
"""
records = json.loads(json_string)
console = Console()
table = Table(title="Sunucu Metrikleri Önizlemesi", show_lines=True)
for key in records[0]:
table.add_column(key, style="cyan" if key == "hostname" else "white")
for row in records:
table.add_row(*[str(v) for v in row.values()])
console.print(table)
# Terminalde kenarlıklarla renk vurgulu tablo oluştururcsv.DictWriter veya DataFrame.to_csv() ile yazın; rich'i yalnızca önizleme için kullanın.Büyük JSON Dosyalarıyla Çalışma
json.load() dosyanın tamamını belleğe okur. 200 MB'lık bir JSON dosyası için bu ~200 MB ham metin artı Python nesne ek yükü anlamına gelir — kolayca 500 MB'ın üzerinde yığın kullanımı. 100 MB'ın üzerindeki dosyalar için girişi ijson ile akışla okuyun ve CSV satırlarını ilerledikçe yazın.
pip install ijson
ijson ile JSON Dizisini CSV'ye Akışla Aktarma
import ijson
import csv
def stream_json_to_csv(json_path: str, csv_path: str) -> int:
"""Büyük JSON dizisini tamamını belleğe yüklemeden CSV'ye dönüştür."""
with open(json_path, "rb") as jf, open(csv_path, "w", newline="", encoding="utf-8") as cf:
# ijson.items üst düzey dizinin her elemanını tek tek verir
records = ijson.items(jf, "item")
first_record = next(records)
fieldnames = list(first_record.keys())
writer = csv.DictWriter(cf, fieldnames=fieldnames)
writer.writeheader()
writer.writerow(first_record)
count = 1
for record in records:
writer.writerow(record)
count += 1
return count
rows = stream_json_to_csv("clickstream_2026_03.json", "clickstream_2026_03.csv")
print(f"{rows} kayıt CSV'ye akışla aktarıldı")NDJSON / JSON Lines — Satır Başına Bir Nesne
NDJSON (Newline-Delimited JSON), JSON Lines veya .jsonl olarak da adlandırılır; sarmalayan dizi olmadan satır başına bir geçerli JSON nesnesi depolar. Bu biçim, günlük işlem hatlarında, olay akışlarında (Kafka, Kinesis) ve Elasticsearch ve BigQuery gibi hizmetlerden toplu dışa aktarmalarda yaygındır. Her satır bağımsız bir JSON nesnesi olduğundan NDJSON dosyasını dosya tutamacı üzerinde düz bir Python for döngüsüyle işleyebilirsiniz — ijson kütüphanesine gerek yoktur. Bellek, dosya boyutundan bağımsız olarak sabit kalır ve bu, kaynak veriniz zaten JSON Lines biçimindeyken en basit akış yaklaşımını oluşturur.
import json
import csv
def ndjson_to_csv(ndjson_path: str, csv_path: str) -> int:
"""Satır sınırlı JSON dosyasını tek seferde bir satır olarak CSV'ye dönüştür."""
with open(ndjson_path, encoding="utf-8") as nf:
first_line = nf.readline()
first_record = json.loads(first_line)
fieldnames = list(first_record.keys())
with open(csv_path, "w", newline="", encoding="utf-8") as cf:
writer = csv.DictWriter(cf, fieldnames=fieldnames)
writer.writeheader()
writer.writerow(first_record)
count = 1
for line in nf:
line = line.strip()
if not line:
continue
try:
record = json.loads(line)
writer.writerow(record)
count += 1
except json.JSONDecodeError:
continue # hatalı biçimli satırları atla
return count
rows = ndjson_to_csv("access_log.ndjson", "access_log.csv")
print(f"{rows} günlük girişi CSV'ye dönüştürüldü")json.load() ile yüklenen 1 GB'lık JSON dizisi, Python nesne ek yükü nedeniyle 3–5 GB RAM tüketebilir. ijson ile bellek dosya boyutundan bağımsız olarak sabit kalır. Küçük bir dosyayı hızlıca dönüştürmeniz gerekiyorsa, bunun yerine JSON to CSV dönüştürücüsüne yapıştırın.Yaygın Hatalar
Sorun: csv modülü \r\n satır sonları yazar. newline='' olmadan Python'un metin modu Windows'ta başka bir \r ekler ve çift aralıklı çıktı üretir.
Çözüm: CSV yazmak için dosya açarken her zaman newline='' geçirin. macOS/Linux'ta zararsızdır.
with open("output.csv", "w") as f:
writer = csv.DictWriter(f, fieldnames=columns)
writer.writeheader()
writer.writerows(data)
# Windows'ta her veri satırı arasında boş satırlarwith open("output.csv", "w", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=columns)
writer.writeheader()
writer.writerows(data)
# Tüm platformlarda temiz çıktıSorun: index=False olmadan pandas, orijinal JSON'da hiç bulunmayan verilerle CSV'yi kirleten otomatik artan satır numarası sütunu (0, 1, 2, ...) başa ekler.
Çözüm: to_csv() fonksiyonuna index=False geçirin. Gerçekten bir indeks sütununa ihtiyacınız varsa df.index.name = 'row_num' ile açıkça adlandırın.
df = pd.read_json("events.json")
df.to_csv("events.csv")
# CSV'de ek isimsiz sütun oluşur: ,event_id,timestamp,...
# Baştaki virgül birçok CSV ayrıştırıcısını bozardf = pd.read_json("events.json")
df.to_csv("events.csv", index=False)
# Temiz CSV: event_id,timestamp,...Sorun: JSON nesnelerinin farklı anahtarları varsa (bazı kayıtlarda isteğe bağlı alanlar), ilk kaydın anahtarlarını fieldnames olarak kullanmak yalnızca sonraki kayıtlarda görünen sütunları sessizce atar.
Çözüm: DictWriter oluşturmadan önce tüm kayıtlardaki benzersiz anahtarları toplayın.
records = json.load(f) writer = csv.DictWriter(out, fieldnames=records[0].keys()) # Yalnızca records[2]'de görünen "discount" alanını kaçırır
records = json.load(f) all_keys = list(dict.fromkeys(k for r in records for k in r)) writer = csv.DictWriter(out, fieldnames=all_keys, restval="") # Her kayıttaki her anahtar sütun olarak dahil edilir
Sorun: csv.DictWriter, iç içe dict'lerde str() çağırır ve "{'city': 'Portland'}"gibi değerler içeren sütunlar üretir — gerçek veri değil ham Python repr.
Çözüm: İç içe nesneleri önce pd.json_normalize() veya özel bir düzleştirme fonksiyonu kullanarak düzleştirin.
records = [{"id": "evt_1", "meta": {"source": "web", "region": "us-west"}}]
writer = csv.DictWriter(f, fieldnames=["id", "meta"])
writer.writerows(records)
# meta sütunu şunu içerir: {'source': 'web', 'region': 'us-west'}import pandas as pd
records = [{"id": "evt_1", "meta": {"source": "web", "region": "us-west"}}]
df = pd.json_normalize(records, sep="_")
df.to_csv("events.csv", index=False)
# Sütunlar: id, meta_source, meta_regioncsv.DictWriter ile pandas — Hızlı Karşılaştırma
Sıfır bağımlılığa ihtiyacınız varsa, JSON'unuz düzse ve betik kısıtlı bir ortamda çalışıyorsa (CI konteynerleri, Lambda fonksiyonları, gömülü Python) csv.DictWriter kullanın. JSON iç içeyse, dışa aktarmadan önce veriyi dönüştürmeniz veya filtrelemeniz gerekiyorsa ya da zaten bir pandas iş akışındaysanız pd.json_normalize() + to_csv() kullanın. Belleğe sığmayan dosyalar için sabit bellekli akış amacıyla ijson ile csv.DictWriter'ı birleştirin.
Hızlı, kodsuz dönüşümler için ToolDeck'teki JSON to CSV dönüştürücüsü herhangi bir Python kurulumu gerektirmeden işi halleder.
Sıkça Sorulan Sorular
pandas olmadan Python'da JSON'u CSV'ye nasıl dönüştürürüm?
Yerleşik json ve csv modüllerini kullanın. JSON dosyasını sözlük listesine ayrıştırmak için json.load() çağrısı yapın, ilk sözlüğün anahtarlarından fieldnames değerlerini çıkarın, bir csv.DictWriter oluşturun, writeheader() ardından writerows() çağrısı yapın. Bu yaklaşımın harici bağımlılığı yoktur ve herhangi bir Python 3.x ortamında çalışır. Ayrıca küçük dosyalar için pandas'tan daha hızlıdır çünkü DataFrame tahsisi ek yükü bulunmaz. JSON nesnelerinin kayıtlar arasında tutarsız anahtarları varsa, eksik sütunları önlemek için fieldnames olarak geçirmeden önce dict.fromkeys(k for r in records for k in r) ile tüm benzersiz anahtarları toplayın.
import json
import csv
with open("orders.json") as f:
records = json.load(f)
with open("orders.csv", "w", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=records[0].keys())
writer.writeheader()
writer.writerows(records)CSV'ye dönüştürürken iç içe JSON'u nasıl ele alırım?
Düz JSON dizileri doğrudan CSV satırlarına eşlenir, ancak iç içe nesnelerin önce düzleştirilmesi gerekir. pandas ile pd.json_normalize() bunu otomatik olarak yapar — iç içe anahtarları nokta ayraçlı adlarla birleştirir (örneğin "address.city"). pandas olmadan, sözlük üzerinde yineleyen ve anahtarları bir sınırlayıcıyla birleştiren özyinelemeli bir fonksiyon yazın. Birden fazla düzeye sahip derin iç içe yapılar için json_normalize hepsini tek geçişte ele alır. sep parametresi anahtar segmentleri arasındaki birleştirme karakterini denetler — alt çizgi genellikle SQL içe aktarmaları ve elektronik tablo formül uyumluluğu için varsayılan noktadan daha güvenlidir.
import pandas as pd
nested_data = [
{"id": "ord_91a3", "customer": {"name": "Ayşe Kaya", "email": "a.kaya@ornek.com"}},
]
df = pd.json_normalize(nested_data, sep="_")
# Sütunlar: id, customer_name, customer_email
df.to_csv("flat_orders.csv", index=False)Windows'ta CSV'mde neden veri satırları arasında boş satırlar oluşuyor?
csv modülü varsayılan olarak \r\n satır sonları yazar. Windows'ta dosyayı metin modunda açmak başka bir \r ekler ve \r\r\n üretir — bu boş satır olarak görünür. Çözüm, her zaman open() fonksiyonuna newline="" geçirmektir. Bu, Python'a satır sonlarını çevirmemesini söyler ve csv modülünün bunları yönetmesine izin verir. Bu kalıp işletim sisteminden bağımsız olarak gereklidir — macOS ve Linux'ta zararsızdır, Windows'ta ise kritiktir. Python belgeleri, CSV yazımı için dosyaları açmanın doğru yolu olarak bunu csv modülü bölümünde açıkça belirtmektedir.
# Yanlış — Windows'ta boş satırlar oluşur
with open("output.csv", "w") as f:
writer = csv.writer(f)
# Doğru — newline="" çift \r'yi önler
with open("output.csv", "w", newline="") as f:
writer = csv.writer(f)Mevcut bir CSV dosyasına JSON kayıtları nasıl eklerim?
Dosyayı ekleme modunda ("a") açın ve aynı fieldnames değerleriyle bir DictWriter oluşturun. Başlık satırı zaten mevcut olduğundan writeheader() çağrısını atlayın. pandas ile to_csv(mode="a", header=False) kullanın. Sütun sırasının mevcut dosyayla eşleştiğinden emin olun, yoksa veriler yanlış sütunlara düşer. Mevcut dosyadaki sütun sırası hakkında emin değilseniz, ekleme için yazıcı oluşturmadan önce dosyayı csv.DictReader ile açın ve fieldnames özniteliğinden alan adlarını okuyun.
import csv
new_records = [
{"order_id": "ord_f4c1", "total": 89.50, "status": "shipped"},
]
with open("orders.csv", "a", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=["order_id", "total", "status"])
writer.writerows(new_records)Python'da büyük bir JSON dosyasını CSV'ye dönüştürmenin en hızlı yolu nedir?
500 MB'ın altındaki dosyalar için pd.read_json() ardından to_csv() en hızlı tek çağrı yaklaşımıdır — pandas dahili olarak optimize edilmiş C kodu kullanır. 500 MB'ın üzerindeki dosyalar için JSON kayıtlarını akışla aktarmak için ijson kullanın ve bunları csv.DictWriter ile satır satır CSV'ye yazın. Bu, dosya boyutundan bağımsız olarak bellek kullanımını sabit tutar. NDJSON dosyaları için (satır başına bir JSON nesnesi) ijson'a hiç gerek yoktur — dosya tutamacı üzerinde düz bir Python for döngüsü her satırı bağımsız olarak işler ve herhangi bir üçüncü taraf kütüphanesi olmadan sabit bellek sağlar.
# Belleğe sığan dosyalar için hızlı
import pandas as pd
df = pd.read_json("large_dataset.json")
df.to_csv("large_dataset.csv", index=False)
# Belleğe sığmayan dosyalar için akış
import ijson, csv
with open("huge.json", "rb") as jf, open("huge.csv", "w", newline="") as cf:
records = ijson.items(jf, "item")
first = next(records)
writer = csv.DictWriter(cf, fieldnames=first.keys())
writer.writeheader()
writer.writerow(first)
for record in records:
writer.writerow(record)Python'da CSV çıktısını dosya yerine stdout'a yazabilir miyim?
Evet. csv.writer() veya csv.DictWriter() fonksiyonlarına dosya nesnesi olarak sys.stdout geçirin. Bu, kabuk betiklerinde çıktıyı pipe'lamak veya hızlı hata ayıklama için kullanışlıdır. pandas ile to_csv(sys.stdout, index=False) çağrısı yapın veya yazdırabileceğiniz bir dize almak için to_csv(None) kullanın. Geçici dosya gerekmez. Windows'ta stdout'a yazarken, stdout varsayılan olarak metin modunda açıldığından çift satır başı sorununu önlemek için önce sys.stdout.reconfigure(newline="") çağrısı yapın.
import csv
import sys
import json
data = json.loads('[{"host":"web-1","cpu":72.3},{"host":"web-2","cpu":45.1}]')
writer = csv.DictWriter(sys.stdout, fieldnames=data[0].keys())
writer.writeheader()
writer.writerows(data)
# host,cpu
# web-1,72.3
# web-2,45.1İlgili Araçlar
Maria is a backend developer specialising in Python and API integration. She has broad experience with data pipelines, serialisation formats, and building reliable server-side services. She is an active member of the Python community and enjoys writing practical, example-driven guides that help developers solve real problems without unnecessary theory.
Priya is a data scientist and machine learning engineer who has worked across the full Python data stack — from raw data ingestion and cleaning to model deployment and monitoring. She is passionate about reproducible research, Jupyter-based workflows, and the practical engineering side of ML. She writes about NumPy, Pandas, data serialisation, and the Python patterns that make data pipelines reliable at scale.