UnicodeDecodeError: 'utf-8' codec can't decode byte 0xe3 in position 16: invalid continuation byte
Fișierul CSV nu e salvat în UTF-8, ci într-o codificare veche (de obicei cp1250 sau latin-1, din Excel pe Windows), iar pandas îl citește implicit ca UTF-8. Spune-i codificarea reală: pd.read_csv("fisier.csv", encoding="cp1250").
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
Un fișier text este de fapt o înșiruire de octeți, iar codificarea (encoding) spune cum se transformă octeții în litere. pandas presupune implicit UTF-8. În UTF-8, literele românești ocupă doi octeți, iar al doilea trebuie să aibă o anumită formă (un „continuation byte”). Când fișierul e salvat în cp1250 (Windows, Europa Centrală), ă este un singur octet, 0xe3, urmat direct de litera următoare, iar decodorul UTF-8 se oprește: „invalid continuation byte”.
Mesajul îți spune octetul problematic (0xe3) și poziția lui în fișier (position 16, numărat de la 0). 0xe3 este ă în cp1250, 0xba este ș, 0xfe este ț, iar 0xe2 și 0xee sunt â și î, deci aproape sigur ai un fișier românesc salvat din Excel sau dintr-un program vechi. Reparația e să citești cu codificarea reală, nu să ștergi diacriticele.
De ce apare: cauzele frecvente
1CSV exportat din Excel pe Windows (cp1250)
import pandas as pd
df = pd.read_csv("clienti.csv")import pandas as pd
df = pd.read_csv("clienti.csv", encoding="cp1250")Excel salvează „CSV (delimitat prin virgulă)” în codificarea Windows a sistemului. Cu encoding="cp1250", octetul 0xe3 este citit corect ca ă.
2Fișier în latin-1 sau ISO-8859-2
import pandas as pd
df = pd.read_csv("export_vechi.csv")import pandas as pd
df = pd.read_csv("export_vechi.csv", encoding="iso-8859-2")Sistemele mai vechi folosesc des ISO-8859-2 (latin-2) pentru română. Încearcă pe rând cp1250, iso-8859-2 și latin-1 și verifică dacă diacriticele arată bine.
3UTF-8 cu BOM, care lasă un caracter ciudat în primul nume de coloană
import pandas as pd
df = pd.read_csv("date.csv")
print(df.columns[0]) # '\ufeffnume'import pandas as pd
df = pd.read_csv("date.csv", encoding="utf-8-sig")
print(df.columns[0]) # 'nume'Nu dă UnicodeDecodeError, dar e problema-soră: fișierul are la început marcajul BOM. utf-8-sig îl elimină, iar df["nume"] nu mai dă KeyError.
Repară eroarea, direct în pagină
Programul de mai jos creează un fișier clienti.csv exact cum l-ar salva Excel pe un Windows în română (codificarea cp1250), apoi îl citește. Citirea dă UnicodeDecodeError. Repară apelul read_csv ca să afișeze tabelul cu diacriticele corecte și numărul de clienți din Brăila.
import pandas as pd
# fișierul, așa cum îl salvează Excel pe Windows (cp1250)
continut = "nume,oras\nAna Pop,Brăila\nIon Toma,Bârlad\nDan Ilie,Brăila\n"
open("clienti.csv", "wb").write(continut.encode("cp1250"))
df = pd.read_csv("clienti.csv")
print(df)
print("Clienți din Brăila:", (df["oras"] == "Brăila").sum())nume oras 0 Ana Pop Brăila 1 Ion Toma Bârlad 2 Dan Ilie Brăila Clienți din Brăila: 2
Indiciu
Adaugă la read_csv parametrul encoding cu codificarea în care a fost salvat fișierul.
Reparația
import pandas as pd
# fișierul, așa cum îl salvează Excel pe Windows (cp1250)
continut = "nume,oras\nAna Pop,Brăila\nIon Toma,Bârlad\nDan Ilie,Brăila\n"
open("clienti.csv", "wb").write(continut.encode("cp1250"))
df = pd.read_csv("clienti.csv", encoding="cp1250")
print(df)
print("Clienți din Brăila:", (df["oras"] == "Brăila").sum())De ce merge
Fișierul are literele ă și â scrise câte un octet, în cp1250. Citit ca UTF-8, octetul 0xe3 (ă) nu formează o literă validă, de aici eroarea. Cu encoding="cp1250", pandas folosește același tabel de litere ca la salvare, deci Brăila și Bârlad apar corect, iar comparația df["oras"] == "Brăila" găsește cele două rânduri.
Alte forme ale mesajului
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xba in position 42: invalid start byteUnicodeDecodeError: 'utf-8' codec can't decode byte 0xe2 in position 7: invalid continuation byteUnicodeDecodeError: 'charmap' codec can't decode byte 0x81 in position 120: character maps to <undefined>
Cum o eviți pe viitor
- Când exporți din Excel, alege „CSV UTF-8 (delimitat prin virgulă)”, nu „CSV”.
- Când primești un fișier de la altcineva, întreabă sau verifică codificarea înainte (multe editoare o afișează în bara de jos).
- Dacă scrii tu fișiere CSV, salvează-le explicit:
df.to_csv("raport.csv", index=False, encoding="utf-8"). - Nu folosi
encoding_errors="ignore"ca reparație: pierzi literele cu diacritice fără să știi.
Întrebări frecvente
Cum aflu codificarea unui fișier?
Deschide-l într-un editor ca VS Code sau Notepad++: codificarea apare în bara de stare. Din Python, poți încerca pe rând câteva codificări și te uiți la diacritice. Pentru fișiere românești, cp1250 rezolvă majoritatea cazurilor.
Ce diferență e între „invalid start byte” și „invalid continuation byte”?
Ambele înseamnă că fișierul nu e UTF-8. „Start byte” apare când octetul nu poate începe o literă în UTF-8, „continuation byte” când o literă a început, dar octetul următor nu se potrivește. Reparația e aceeași: parametrul encoding cu codificarea reală.
Pot folosi encoding="latin-1" pentru orice fișier?
latin-1 nu dă niciodată eroare, pentru că orice octet are o literă asociată, dar asta nu înseamnă că literele sunt corecte. Un fișier cp1250 citit ca latin-1 îți arată º în loc de ș. Verifică mereu rezultatul.
Erori înrudite
FileNotFoundError: [Errno 2] No such file or directory: 'vanzari.csv' pd.read_csv nu găsește fișierul la calea pe care i-ai dat-o: numele e scris altfel sau fișierul e în alt folder decât cel din care rulezi. Verifică numele exact (cu extensia) și folosește o cale corectă, relativă la folderul de lucru, sau o cale absolută. pandas.errors.ParserError: Error tokenizing data. C error: Expected 5 fields in line 4, saw 6 Un rând din CSV are mai multe valori decât antetul, de obicei din cauza unei virgule în interiorul unei valori (o zecimală scrisă cu virgulă sau un text fără ghilimele). Pune valorile cu virgulă între ghilimele sau citește cu separatorul corect (sep=";"). KeyError: 'Pret' DataFrame-ul nu are o coloană cu exact numele 'Pret'. Coloanele sunt sensibile la majuscule, spații și diacritice: afișează print(df.columns.tolist()) și folosește numele exact, de exemplu df["pret"]. Învață Python pentru analiza datelor de la zero, cu exerciții la fiecare lecție
Curs Data Analysis with Python: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.
