IOPub Data Rate Exceeded in Jupyter Notebook — What It Means

You run a cell that prints a large table, starts a chatty training job, or loops over thousands of log lines, and Jupyter responds with IOPub data rate exceeded. The kernel often pauses or appears to freeze until things calm down, and the output you wanted never fully arrives. This is not a bug in your code. It is Jupyter’s safety valve against runaway output flooding the browser. This guide explains what the limit protects, how to reduce output at the source, and how to raise the limit properly when your workflow genuinely needs it.

Quick Answer

The warning means a cell produced output faster than Jupyter allows the kernel to send to your browser — by default around 1 MB per second by default in classic setups. The practical fix is to print less: show summaries, samples, and counts instead of entire datasets. If you truly need heavy output, raise the limit when launching Jupyter, for example jupyter notebook --NotebookApp.iopub_data_rate_limit=10000000, or the ServerApp equivalent on JupyterLab, and restart the server.

What IOPub Is and Why It Has a Limit

IOPub is the channel over which the kernel broadcasts output — print statements, results, images, and status — to the front end. Without a cap, a single misbehaving cell, such as printing inside a tight million-iteration loop, could push gigabytes toward the browser tab, consuming memory until the tab or the whole machine becomes unusable. The rate limit is a circuit breaker: when output exceeds the configured bytes per second, Jupyter throttles the stream and shows the IOPub data rate exceeded message, sometimes pausing execution briefly. Your computation is usually unharmed; it is the display pipe that is overwhelmed.

Common triggers share one trait: unbounded output. Printing a whole dataframe instead of its head, logging every iteration of a long job, returning a giant list as a cell result, or an accidental infinite print loop will all trip it. If the kernel seems broken rather than merely chatty, that is a different failure family — start with our guide to fixing Jupyter kernel errors instead.

Fix 1: Print Less, But Print Smarter

1. Summarise collections instead of dumping them. For pandas, use df.head(), df.shape, and df.describe(). For lists, print len(items) and the first few elements with items[:5].
2. Log progress, not data. Inside loops, print every 100th or 1000th iteration with a condition like if i % 1000 == 0: print(i), and include a count or percentage rather than the row contents.
3. Send bulk output to a file. When you genuinely need every line, write it to a text or CSV file with a normal file write, and print only a confirmation plus the file path. Files have no rate limit.
4. Clear old output. A notebook stuffed with megabytes of previous output stays heavy. Use Edit → Clear All Outputs (or the equivalent in JupyterLab) and save, then rerun only what you need.
5. Check for an accidental flood. If the warning appears instantly on a small cell, look for a print inside a fast loop or a widget or library that logs verbosely, and reduce its logging level.

Fix 2: Raise the Limit at Launch

When heavy output is legitimate — rich progress reporting from a framework, for instance — raise the ceiling when you start the server:

• Classic Notebook: jupyter notebook --NotebookApp.iopub_data_rate_limit=10000000 raises the cap to about 10 MB per second.
• JupyterLab / Jupyter Server: jupyter lab --ServerApp.iopub_data_rate_limit=10000000 uses the newer ServerApp setting.
• Make it permanent: generate a config file with jupyter notebook --generate-config (or jupyter server --generate-config), then set the iopub_data_rate_limit option in that file so every launch inherits it.

The Jupyter Server documentation describes the configuration system and where config files live on each platform. Remember the trade-off: a higher limit re-opens the door to a flooded browser, so raise it in steps rather than by orders of magnitude.

Fix 3: Tame Chatty Libraries

Some frameworks print progress lines continuously. Most expose a verbosity switch: training libraries have verbose flags, download tools have progress toggles, and Python’s logging module has levels. Setting a library to warnings-only, or redirecting its progress bar to a file, often eliminates the warning without touching Jupyter’s settings at all. In notebooks, assigning an expression’s result to a variable, or ending the line with a semicolon, also suppresses the automatic display of large return values that would otherwise flood the output area.

Common Mistakes to Avoid

• Raising the limit to an astronomical number as the first response. You remove the safety valve and keep the flooding code. Reduce output first; tune the limit second.
• Confusing the rate limit with a kernel crash. With IOPub throttling, the kernel is alive and usually finishes the cell; the output is merely delayed or truncated. Restarting the kernel loses your variables for no reason.
• Printing inside tight loops for debugging. A million prints is the fastest route to this warning. Aggregate the values and print one summary after the loop.
• Editing the wrong config option name. NotebookApp applies to the classic server and ServerApp to the newer one; using the wrong name silently does nothing, which looks like the fix failed.

A Related Habit: Keep Notebook Output Lean

The rate limit protects the live session, but a sibling problem waits in the saved file: notebooks store their output inside the .ipynb file itself. A notebook that printed thousands of rows or several large images can grow to tens of megabytes, making it slow to open, painful to share, and miserable in version control, where every rerun rewrites the entire file’s output sections. The same discipline that prevents IOPub warnings prevents the bloat: print summaries instead of datasets, display a sample of rows, and clear all outputs before committing or sharing a notebook unless the results themselves are the deliverable. Some teams adopt tools that strip outputs automatically on commit. Even without tooling, a final “clear outputs, save” pass at the end of a session keeps notebooks small, diffs readable, and reopening instant — a quiet habit that complements everything else in this guide.

Conclusion

IOPub data rate exceeded means your notebook tried to display output faster than Jupyter’s safety limit allows. Cut the flood at the source with summaries, sampling, and file output, silence chatty libraries, and only then raise iopub_data_rate_limit at launch if your workflow still needs more headroom. The limit is a guard rail — work with it, not against it.

Frequently Asked Questions

Did the cell still run to completion?

Usually yes. The throttling affects the delivery of output to the browser, not the computation itself. The kernel may pause output briefly while the rate settles, and some displayed output can be dropped, but variables and results are normally intact. Check a known value from the cell to confirm.

What is the default IOPub data rate limit?

In classic Jupyter Notebook the long-standing default was 1,000,000 bytes per second (about 1 MB/s). Newer Jupyter Server versions may use higher defaults. Whatever your version, the fix paths are the same: reduce output, or raise the value explicitly with the NotebookApp or ServerApp setting.

Why does the warning appear even for small notebooks?

Because the limit is about rate, not total size. A tiny cell that prints frantically in a burst can exceed the per-second allowance even though the total output is modest. Images count too: returning several large plots at once can trip the limit in a single cell.

Can I disable the limit entirely?

Setting the limit to a very large number effectively disables it, but it is not recommended. The protection exists because a flooded browser tab can freeze or crash, taking your session view with it. If you must raise it, do so modestly and fix the output habits that made it necessary.

How do I stop a cell that is flooding right now?

Interrupt the kernel from the toolbar stop button or Kernel → Interrupt. The flood stops with the execution. Then edit the cell to reduce its output before running it again, and clear the accumulated output so the notebook file stays lean.