UnicodeEncodeError: 'ascii' codec can't encode character '\u0219' in position 3: ordinal not in range(128)
Încerci să transformi în bytes (să scrii, să afișezi sau să trimiți) un text cu diacritice folosind un encoding care nu le are, de obicei ASCII. Folosește UTF-8: `text.encode("utf-8")`, `open(..., encoding="utf-8")` sau setează `PYTHONIOENCODING=utf-8` pentru terminal.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
Encode înseamnă transformarea textului în octeți. ASCII are doar 128 de caractere (litere englezești, cifre, semne), deci nu are ș, ț, ă, î sau â. Când textul are un caracter în afara acestui set, encode("ascii") nu are cum să-l scrie și ridică UnicodeEncodeError. Mesajul arată caracterul în formă Unicode ('\u0219' este ș), poziția lui și motivul: codul caracterului nu e sub 128.
În practică, ASCII ajunge să fie folosit fără să-l ceri: un terminal sau un server configurat cu locale C/POSIX, un container Docker minimal, un program vechi care cere ASCII, sau Windows cu cp1252, care dă 'charmap' codec can't encode character. Apare la print, la scrierea în fișiere fără encoding explicit sau la trimiterea de antete HTTP și emailuri.
De ce apare: cauzele frecvente
1Encode explicit în ASCII
oras = "Brașov"
date = oras.encode("ascii")oras = "Brașov"
date = oras.encode("utf-8")UTF-8 poate reprezenta orice caracter Unicode, inclusiv diacriticele românești.
2Fișier scris fără encoding pe un sistem configurat ASCII
with open("raport.txt", "w") as f:
f.write("Total încasări: 500")with open("raport.txt", "w", encoding="utf-8") as f:
f.write("Total încasări: 500")Cu encoding explicit, rezultatul nu mai depinde de setările sistemului.
3Terminal sau container fără UTF-8
# Dockerfile
FROM python:3.12-slim
CMD ["python", "app.py"]# Dockerfile
FROM python:3.12-slim
ENV PYTHONIOENCODING=utf-8 LANG=C.UTF-8
CMD ["python", "app.py"]Variabilele de mediu spun lui Python să folosească UTF-8 pentru intrare și ieșire.
Repară eroarea, direct în pagină
Codul de mai jos pregătește numele orașelor pentru trimitere ca bytes și dă UnicodeEncodeError: 'ascii' codec can't encode character '\u0219' .... Folosește UTF-8, ca programul să afișeze Brașov: 7 bytes, Cluj: 4 bytes și Timișoara: 10 bytes.
orase = ["Brașov", "Cluj", "Timișoara"]
for oras in orase:
date = oras.encode("ascii")
print(f"{oras}: {len(date)} bytes")Brașov: 7 bytes Cluj: 4 bytes Timișoara: 10 bytes
Indiciu
Schimbă encoding-ul din encode într-unul care are diacriticele românești.
Reparația
orase = ["Brașov", "Cluj", "Timișoara"]
for oras in orase:
date = oras.encode("utf-8")
print(f"{oras}: {len(date)} bytes")De ce merge
ASCII are doar 128 de caractere, fără ș, așa că encode("ascii") se oprește la prima diacritică. UTF-8 poate reprezenta orice caracter: literele obișnuite ocupă câte un octet, iar ș ocupă doi. De aceea Brașov, cu 6 litere, are 7 bytes, iar Cluj, fără diacritice, are 4.
Alte forme ale mesajului
UnicodeEncodeError: 'charmap' codec can't encode character '\u0219' in position 3: character maps to <undefined>UnicodeEncodeError: 'latin-1' codec can't encode character '\u021b' in position 10: ordinal not in range(256)UnicodeEncodeError: 'ascii' codec can't encode characters in position 3-4: ordinal not in range(128)
Cum o eviți pe viitor
- Folosește UTF-8 peste tot:
encoding="utf-8"la fișiere,.encode("utf-8")la conversii. - În containere și pe servere, setează
LANG=C.UTF-8șiPYTHONIOENCODING=utf-8. - Pe Windows, activează modul UTF-8 al lui Python cu
PYTHONUTF8=1. - Dacă un sistem vechi acceptă doar ASCII, elimină diacriticele controlat (cu
unicodedata.normalize), nu cuerrors="ignore".
Întrebări frecvente
De ce print merge pe calculatorul meu, dar nu pe server?
Pentru că print encodează textul cu encoding-ul terminalului. Pe calculatorul tău acesta e UTF-8, iar pe server sau într-un container poate fi ASCII. Setează PYTHONIOENCODING=utf-8 sau LANG=C.UTF-8 în mediul serverului.
Pot pur și simplu să ignor caracterele problematice?
Poți, cu encode("ascii", errors="ignore"), dar Brașov devine Braov. Mai bine elimini diacriticele (ș → s) cu unicodedata, sau folosești UTF-8.
Erori înrudite
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xe9 in position 15: invalid continuation byte Fișierul (sau datele) nu e salvat în UTF-8, ci în alt encoding, de obicei unul vechi de Windows (`cp1250`, `latin-1`) sau e un Excel salvat ca CSV. Deschide-l cu encoding-ul corect: `open("fisier.csv", encoding="cp1250")`, sau resalvează-l ca UTF-8. TypeError: a bytes-like object is required, not 'str' Amesteci bytes (`b"..."`) cu texte (`str`): de exemplu faci `split(",")` pe date binare, cauți un text într-un bytes sau scrii text într-un fișier deschis cu `"wb"`. Decodează datele cu `.decode("utf-8")` sau lucrează doar cu bytes (`b","`). SyntaxError: invalid character '“' (U+201C) În cod ai ghilimele „inteligente” (“ ” sau ‘ ’), de obicei copiate din Word, dintr-un PDF, din Slack sau de pe un site. Python acceptă doar ghilimelele drepte " și '. Înlocuiește-le și eroarea dispare. Învață Python de la zero, cu exerciții la fiecare lecție
Curs Python: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.
