Don't warn about plotly's default kopts under a kaleido sync server

Author: jayzhou2309

CHANGELOG.md

@@ -7,6 +7,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ### Fixed
 - Fix concurrent first access to lazily initialized graph object properties, which could raise `ValueError("Invalid value")` [[#3441](https://github.com/plotly/plotly.py/issues/3441)], with thanks to @hb1915 for the contribution!
 - Fix `px.sunburst`, `px.treemap` and `px.icicle` listing sectors in a different order on every run when `path` is used with a Polars DataFrame; sectors now follow their order of first appearance for all dataframe backends [[#5765](https://github.com/plotly/plotly.py/issues/5765)], with thanks to @Irahan2 for the contribution!
+- Fix `write_image`, `to_image` and `write_images` emitting `UserWarning: The kopts argument is ignored if using a server.` on every call under `kaleido.start_sync_server()` when no Kaleido options are set; the warning still appears when `plotly.io.defaults` sets `plotlyjs`, `mathjax` or custom `headers` [[#5786](https://github.com/plotly/plotly.py/issues/5786)], with thanks to @jayzhou2309 for the contribution!
 
 
 ## [7.1.0] - 2026-09-15

plotly/io/_defaults.py

@@ -1,5 +1,9 @@
 # Default settings for image generation
 
+# This header is necessary to comply with Open Street Map tile policy:
+# https://openstreetmap.github.io/owg-website/policies/tiles/#31-identification
+DEFAULT_HEADERS = {"X-Requested-With": "plotly.py"}
+
 
 class _Defaults(object):
     """
@@ -14,9 +18,7 @@ def __init__(self):
         self.mathjax = None
         self.topojson = None
         self.plotlyjs = None
-        # This header is necessary to comply with Open Street Map tile policy:
-        # https://openstreetmap.github.io/owg-website/policies/tiles/#31-identification
-        self.headers = {"X-Requested-With": "plotly.py"}
+        self.headers = dict(DEFAULT_HEADERS)
 
 
 defaults = _Defaults()

plotly/io/_kaleido.py

@@ -1,3 +1,4 @@
+from contextlib import contextmanager
 import os
 import json
 from pathlib import Path
@@ -8,7 +9,7 @@
 
 import plotly
 from plotly.io._utils import validate_coerce_fig_to_dict, broadcast_args_to_dicts
-from plotly.io._defaults import defaults
+from plotly.io._defaults import defaults, DEFAULT_HEADERS
 from _plotly_utils.optional_imports import get_module
 
 kaleido = get_module("kaleido", should_load=True)
@@ -35,6 +36,18 @@
 _KALEIDO_AVAILABLE = None
 
 
+@contextmanager
+def _ignore_default_kopts_warning(kopts):
+    # A running kaleido sync server ignores kopts and warns about any. Only
+    # warn when the user set an option, not for plotly's default headers.
+    with warnings.catch_warnings():
+        if kopts == {"headers": DEFAULT_HEADERS}:
+            warnings.filterwarnings(
+                "ignore", message="The kopts argument", category=UserWarning
+            )
+        yield
+
+
 def kaleido_available() -> bool:
     """
     Returns True if Kaleido version 1.0.0 or greater is installed, otherwise False.
@@ -182,17 +195,18 @@ def to_image(
             or defaults.default_height
         )
 
-        img_bytes = kaleido.calc_fig_sync(
-            fig_dict,
-            opts=dict(
-                format=format or defaults.default_format,
-                width=width,
-                height=height,
-                scale=scale or defaults.default_scale,
-            ),
-            topojson=defaults.topojson,
-            kopts=kopts,
-        )
+        with _ignore_default_kopts_warning(kopts):
+            img_bytes = kaleido.calc_fig_sync(
+                fig_dict,
+                opts=dict(
+                    format=format or defaults.default_format,
+                    width=width,
+                    height=height,
+                    scale=scale or defaults.default_scale,
+                ),
+                topojson=defaults.topojson,
+                kopts=kopts,
+            )
     except ChromeNotFoundError:
         raise RuntimeError(PLOTLY_GET_CHROME_ERROR_MSG)
 
@@ -430,10 +444,11 @@ def write_images(
             kopts["mathjax"] = defaults.mathjax
         if defaults.headers:
             kopts["headers"] = defaults.headers
-        kaleido.write_fig_from_object_sync(
-            kaleido_specs,
-            kopts=kopts,
-        )
+        with _ignore_default_kopts_warning(kopts):
+            kaleido.write_fig_from_object_sync(
+                kaleido_specs,
+                kopts=kopts,
+            )
     except ChromeNotFoundError:
         raise RuntimeError(PLOTLY_GET_CHROME_ERROR_MSG)