python/cpython · error · ValueError

binary mode doesn't take a newline argument

Error message

binary mode doesn't take a newline argument

What it means

Raised by io.open() as a ValueError when binary mode ('b') is combined with a non-None newline argument. newline controls universal-newline translation for text streams; binary streams return bytes verbatim, so newline translation cannot apply.

Source

Thrown at Lib/_pyio.py:227

    creating = "x" in modes
    reading = "r" in modes
    writing = "w" in modes
    appending = "a" in modes
    updating = "+" in modes
    text = "t" in modes
    binary = "b" in modes
    if text and binary:
        raise ValueError("can't have text and binary mode at once")
    if creating + reading + writing + appending > 1:
        raise ValueError("can't have read/write/append mode at once")
    if not (creating or reading or writing or appending):
        raise ValueError("must have exactly one of read/write/append mode")
    if binary and encoding is not None:
        raise ValueError("binary mode doesn't take an encoding argument")
    if binary and errors is not None:
        raise ValueError("binary mode doesn't take an errors argument")
    if binary and newline is not None:
        raise ValueError("binary mode doesn't take a newline argument")
    if binary and buffering == 1:
        import warnings
        warnings.warn("line buffering (buffering=1) isn't supported in binary "
                      "mode, the default buffer size will be used",
                      RuntimeWarning, 2)
    raw = FileIO(file,
                 (creating and "x" or "") +
                 (reading and "r" or "") +
                 (writing and "w" or "") +
                 (appending and "a" or "") +
                 (updating and "+" or ""),
                 closefd, opener=opener)
    result = raw
    try:
        line_buffering = False
        if buffering == 1 or buffering < 0 and raw._isatty_open_only():
            buffering = -1
            line_buffering = True

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Drop newline for binary opens — bytes are returned untranslated by definition.
2. In shared helpers, pass newline only in text mode.
3. If you were using newline='' for csv.reader, keep the file in text mode ('r', encoding=...) — csv accepts text streams.

Example fix

// before
with open('data.csv', 'rb', newline='') as f:   # ValueError
    rows = list(csv.reader(f))

// after
with open('data.csv', 'r', encoding='utf-8', newline='') as f:
    rows = list(csv.reader(f))
# binary alternative (no newline kwarg):
with open('data.csv', 'rb') as f:
    raw = f.read()

def open_any(path, mode='r', newline=None, **kw):
    if 'b' in mode:
        newline = None
    return open(path, mode, newline=newline, **kw)

def newline_allowed(mode: str) -> bool:
    return 'b' not in mode

When it happens

Trigger: open('f.bin', 'rb', newline='\n'), or wrappers forwarding newline='' unconditionally (a very common idiom for CSV files: open(p, newline='') — which is only valid in text mode).

Common situations: CSV/record parsing code where newline='' is cargo-culted onto every open() and then someone switches the mode to 'rb' (e.g. to use csv with bytes or to hash a file); cross-platform line-ending work ported from text to binary.

Related errors

• can't have text and binary mode at once
• binary mode doesn't take an encoding argument
• binary mode doesn't take an errors argument
• can't have read/write/append mode at once
• must have exactly one of read/write/append mode

AI-assisted analysis of python/cpython@bc6749cc3b (2026-08-14). Data as JSON: /api/errors/3a0c97ac56b5346c. Report an issue: GitHub.