Streamlit's Plotly Chart: Fixing The Kwargs Deprecation Warning

Are you encountering a pesky deprecation warning when using Streamlit's st.plotly_chart function, even when you're just trying to set the width or height of your plots? You're not alone! Many users have reported seeing this warning, often when passing arguments like width="content" or height="auto". It's a bit confusing because the warning suggests issues with variable keyword arguments (kwargs), but you might not be explicitly passing any extra keywords yourself. Let's dive into what's happening and how to navigate this common hiccup.

Understanding the plotly_chart Kwargs Deprecation Warning

The core of the issue lies in how Streamlit handles arguments passed to st.plotly_chart. Previously, it was more lenient with how you could pass arguments, including those intended for the underlying Plotly figure itself. However, as Streamlit evolves, it aims to provide a cleaner and more robust API. Part of this evolution involved deprecating the direct use of variable keyword arguments (**kwargs) for passing Plotly configurations. The intention was to steer users towards a more structured way of configuring their charts, primarily through the config argument in Plotly, and specific arguments like width and height that Streamlit directly supports.

When you use st.plotly_chart(fig, width="content"), Streamlit is processing the width argument. However, somewhere in the internal handling of arguments, it seems that the width parameter (or potentially other direct arguments like height) is being caught by a check designed to flag the use of general **kwargs. This check, intended to prevent users from passing arbitrary Plotly figure layout arguments directly to st.plotly_chart, is inadvertently triggering the deprecation warning even when documented and supported parameters like width are used. The warning message, specifically mentioning "Variable keyword arguments for st.plotly_chart have been deprecated and will be removed in a future release. Use the config argument instead to specify Plotly configuration options," is quite direct. However, the context in which it's appearing, when using standard width/height parameters, is what causes the confusion. It implies that width="content" is being treated as a variable keyword argument, which isn't ideal for user experience as it's a documented feature.

This situation is particularly frustrating because it's a regression for users who relied on this functionality in previous versions. The deprecation warning disrupts the smooth development process, prompting investigation into something that appears to be an internal handling issue rather than a direct user error in argument passing. The goal of Streamlit is to make app development intuitive, and such warnings, when misplaced, can create unnecessary friction. The team is aware of this behavior, and it's likely a matter of refining the argument parsing logic within st.plotly_chart to correctly differentiate between intended, documented parameters and truly arbitrary **kwargs.

Reproducible Code Example and Steps to Reproduce

To help illustrate the problem, here's a simplified code snippet that triggers the warning:

import plotly.graph_objects as go
import streamlit as st

# Create a basic Plotly figure
fig = go.Figure()
fig.add_trace(go.Barpolar(r=[1], theta=[0], width=[120]))
fig.update_layout(width=500, height=360)

# Use st.plotly_chart with width="content"
st.plotly_chart(fig, width="content")

Steps to Reproduce:

1. Ensure you have Streamlit version 1.50.0 (or a similar recent version) and Plotly installed.
2. Run the Python script containing the code above.
3. Observe the Streamlit application output. You should see the generated chart, and in your terminal or Streamlit's developer console, you will find the deprecation warning related to kwargs.

This example is straightforward and highlights the exact scenario where the warning appears. It's not dependent on complex configurations or unusual Plotly figures. The mere act of specifying width="content" triggers the warning, which is the core of the reported issue. Users might also encounter similar warnings with height="auto" or other similar string-based sizing parameters, as the underlying mechanism is likely the same. The expectation is that documented parameters, even those controlling dimensions, should not trigger warnings related to the deprecation of arbitrary keyword arguments.

Expected vs. Current Behavior

Let's clarify what's happening and what we'd ideally want to see.

Expected Behavior: When updating to newer versions of Streamlit, it's expected that functionalities continue to work as documented, or at least offer clear migration paths. In the context of st.plotly_chart, the documentation indicates that parameters like width and height are supported for controlling the dimensions of the displayed chart. Therefore, when you pass width="content" (or other valid dimension settings), the chart should render correctly without any deprecation warnings. The warning related to kwargs should only appear when users are attempting to pass genuinely unrecognized or deprecated variable keyword arguments that are not explicitly handled by Streamlit or Plotly's core configuration.

Current Behavior: As observed and reported, the current behavior is that using st.plotly_chart(fig, width="content") (and potentially similar uses of height) results in the following deprecation warning appearing:

Variable keyword arguments for st.plotly_chart have been deprecated and will be removed in a future release. Use the config argument instead to specify Plotly configuration options.

This warning is triggered by the following code snippet introduced in recent Streamlit versions:

if kwargs:
    show_deprecation_warning(
        "Variable keyword arguments for st.plotly_chart have been "
        "deprecated and will be removed in a future release. Use the "
        "config argument instead to specify Plotly configuration "
        "options."
    )

The issue is that the if kwargs: condition is evaluating to true, or a similar internal logic is incorrectly identifying the width parameter as a general kwargs that should be deprecated. This suggests that the width argument, when passed directly to st.plotly_chart, is not being properly intercepted and handled as a specific, documented parameter before the general kwargs check occurs. This is a regression because, in older versions, this setup would not produce the warning. The user experience is degraded as they are warned about a practice they are not intentionally engaging in, leading to confusion and a loss of confidence in the library's stability or documentation.

Why This Matters: User Experience and API Clarity

This seemingly minor warning might feel like a small bug, but it has significant implications for user experience and the clarity of Streamlit's API. When developers see deprecation warnings, they generally assume they are doing something wrong or using an outdated feature. In this case, they are using a documented feature (`width=