EC
BrokenPipeError
PythonERRORI/O ErrorHIGH confidence

Pipe is broken

What this means

A subclass of `ConnectionError`, raised when trying to write to a pipe or socket for which the reading end has been closed. It's a common issue in networked applications and command-line tools.

Why it happens
  1. 1A web client disconnects before the server has finished sending the full response.
  2. 2In a command-line pipeline (e.g., `python my_script.py | head`), the downstream command (`head`) closes its input pipe after reading enough data.
  3. 3A remote process connected via a socket crashes or closes the connection unexpectedly.
How to reproduce

This error is often seen when piping a script's output to a tool like `head`, which closes the pipe once it has read enough lines.

trigger — this will error
trigger — this will error
# To run this, save it as a file (e.g., looper.py) and run from your shell:
# python looper.py | head -n 5
import sys
try:
    for i in range(1000):
        print(f"Line {i}")
        sys.stdout.flush()
except BrokenPipeError:
    # This block will likely not execute because the process just exits.
    # The error is primarily to signal the OS.
    sys.stderr.write("Broken pipe detected!
")

expected output

Line 0
Line 1
Line 2
Line 3
Line 4
(The script then terminates with a BrokenPipeError, which may or may not be visible)

Fix 1

Gracefully handle the `BrokenPipeError`

WHEN Your application needs to shut down cleanly when a client disconnects.

Gracefully handle the `BrokenPipeError`
import sys
try:
    # ... code that writes to stdout or a socket
    sys.stdout.write("some data
")
except BrokenPipeError:
    # The client has disconnected.
    # Log the event and exit gracefully. No need to continue.
    print("Client disconnected, shutting down.", file=sys.stderr)
    sys.exit(0)

Why this works

By catching `BrokenPipeError`, your server or script can recognize that the other end of the connection is gone and perform a clean shutdown, preventing further errors.

Fix 2

Ignore `SIGPIPE` at the OS level (Advanced/Unix-specific)

WHEN You are writing a daemon or server where a broken pipe is a normal event and not an error.

Ignore `SIGPIPE` at the OS level (Advanced/Unix-specific)
# This is advanced and platform-specific (Unix-like OS)
import signal
# This tells the OS not to send the SIGPIPE signal,
# so a write to a broken pipe will raise EPIPE, which Python
# translates to BrokenPipeError, which can be handled.
try:
    signal.signal(signal.SIGPIPE, signal.SIG_DFL)
except AttributeError:
    # Not on a Unix-like system
    pass

Why this works

This low-level signal handling allows a program to treat pipe closures as a manageable exception rather than a fatal signal, which is the default behavior in some environments.

Code examples
Triggerpython
import sys
for i in range(1000):
    print(i)  # BrokenPipeError when piped to head and pipe closes
Handle with try/exceptpython
try:
    sys.stdout.write(data)
except BrokenPipeError:
    sys.exit(0)  # client disconnected — exit cleanly
Avoid by checking pipepython
import signal, sys
try:
    signal.signal(signal.SIGPIPE, signal.SIG_DFL)
except AttributeError:
    pass  # Windows does not have SIGPIPE
What not to do

✕ Treating a broken pipe as a critical bug

In many contexts, especially web servers and command-line tools, a broken pipe is a normal operational event (a user closed their browser, `head` finished its work). It should usually be handled by stopping the current operation gracefully, not by crashing.

Version notes

Sources
Official documentation ↗

cpython/Objects/exceptions.c

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Python errors