Python'da JSON'dan CSV'ye — DictWriter + pandas Örnekleri

·Backend Developer·İnceleyenPriya Sharma·Yayınlandı

Ü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.

Before · json
After · json
[{"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.

Python 3.8+ — minimal json to csv örneği
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.95

open() ü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.

Python 3.8+ — JSON dosyasını oku, CSV dosyasını yaz
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ür

extrasaction="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.

Not: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.

Python 3.8+ — CSV yazmadan önce datetime ve Decimal'i ön işleme
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 GmbH

prepare_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.

Uyarı: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.

Parametre
Tür
Varsayılan
Açıklama
f
dosya nesnesi
(zorunlu)
write() metoduna sahip herhangi bir nesne — genellikle open() ile elde edilir
fieldnames
dizi
(zorunlu)
CSV çıktısında sütun sırasını belirleyen anahtar listesi
restval
str
""
fieldnames içindeki bir anahtar sözlükte yoksa yazılan değer
extrasaction
str
"raise"
"raise" fazla anahtarlar için ValueError fırlatır; "ignore" sessizce yok sayar
dialect
str / Dialect
"excel"
Önceden tanımlı biçimlendirme kuralları — "excel", "excel-tab" veya "unix"
delimiter
str
","
Alanları ayıran tek karakter — TSV çıktısı için "\t" kullanın
quotechar
str
"
Sınırlayıcı içeren alanları tırnak içine almak için kullanılan karakter
quoting
int
csv.QUOTE_MINIMAL
Tırnaklama uygulanacağı zamanı denetler — MINIMAL, ALL, NONNUMERIC, NONE
lineterminator
str
"\r\n"
Her satırdan sonra eklenen dize — Unix tarzı çıktı için "\n" olarak geçersiz kılın

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.

Python 3.8+ — pandas read_json ardından to_csv
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.

Python 3.8+ — json_normalize kullanarak iç içe JSON'u düzleştirme
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, total

sep="_" 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.

Parametre
Tür
Varsayılan
Açıklama
path_or_buf
str / Path / None
None
Dosya yolu veya tampon — None, CSV'yi dize olarak döndürür
sep
str
","
Alan sınırlayıcı — TSV için "\t" kullanın
index
bool
True
Satır indeksini ilk sütun olarak yazar — neredeyse her zaman False olarak ayarlayın
columns
list
None
Çıktıda sütunları alt kümeleme ve yeniden sıralama
header
bool / list
True
Sütun adlarını yazar — mevcut dosyaya eklerken False yapın
encoding
str
"utf-8"
Çıktı kodlaması — Windows'ta Excel uyumluluğu için "utf-8-sig" kullanın
na_rep
str
""
Eksik değerlerin (NaN, None) dize gösterimi
quoting
int
csv.QUOTE_MINIMAL
Alanların ne zaman tırnak içine alınacağını denetler
Python 3.8+ — yaygın parametre geçersiz kılmalarıyla to_csv
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

Python 3.8+ — hata işlemeyle JSON dosyasını CSV'ye dönüştür
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

Python 3.8+ — API'den JSON çek ve CSV olarak kaydet
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ı")
Not:Yukarıdaki örnek, betiği bağımlılıksız tutmak için standart kütüphanedeki 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.

bash — tek satırlık json'dan csv'ye dönüşüm
# 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
bash — argparse ile bağımsız CLI betiği
# 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)
" "$@"
bash — karmaşık dönüşümler için jq + csvkit kullanımı
# 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.csv

Miller (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.

bash — pyarrow kurulumu
pip install pyarrow
Python 3.8+ — daha hızlı CSV yazımı için pyarrow ile pandas
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.

bash — rich kurulumu
pip install rich
Python 3.8+ — rich ile terminalde CSV çıktısını önizle
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şturur
Uyarı:Rich yalnızca terminal görüntüleme içindir. CSV dosyaları oluşturmak için kullanmayın — çıktıyı bozacak ANSI kaçış kodları ekler. Dosyalara csv.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.

bash — ijson kurulumu
pip install ijson

ijson ile JSON Dizisini CSV'ye Akışla Aktarma

Python 3.8+ — büyük JSON dizisini sabit bellekle CSV'ye akışla aktar
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.

Python 3.8+ — NDJSON'u satır satır CSV'ye dönüştür
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ü")
Not:JSON dosyası 100 MB'ı aştığında akışa geçin. 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

open() içinde newline='' eksikliği — Windows'ta boş satırlar

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.

Before · Python
After · Python
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ırlar
with 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ı
pandas to_csv() içinde index=False unutmak

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.

Before · Python
After · Python
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ı bozar
df = pd.read_json("events.json")
df.to_csv("events.csv", index=False)
# Temiz CSV: event_id,timestamp,...
Tutarsız anahtarlara sahip kayıtlarda records[0].keys() kullanmak

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.

Before · Python
After · Python
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
İç içe dict'leri düzleştirmeden doğrudan CSV'ye yazmak

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.

Before · Python
After · Python
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_region

csv.DictWriter ile pandas — Hızlı Karşılaştırma

Yöntem
İç İçe JSON
Özel Tipler
Akış
Bağımlılıklar
Kurulum Gerektirir
csv.DictWriter
✗ (elle düzleştirme)
✓ (satır satır)
Yok
Hayır (stdlib)
csv.writer
✓ (satır satır)
Yok
Hayır (stdlib)
pd.DataFrame.to_csv()
✗ (yalnızca düz)
✓ (dtype aracılığıyla)
pandas + numpy
pip install
pd.json_normalize() + to_csv()
✓ (dtype aracılığıyla)
pandas + numpy
pip install
csv.writer + json_flatten
flatten_json
pip install
jq + csvkit (CLI)
✓ (jq aracılığıyla)
N/A
jq, csvkit
Sistem kurulumu

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.

Python
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.

Python
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.

Python
# 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.

Python
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.

Python
# 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.

Python
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

MS
Maria SantosBackend Developer

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.

PS
Priya SharmaTeknik İnceleyici

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.