Install & Compatibility
Where this runs
tested against v0.0.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Figure
✓ from plotly.graph_objects import Figure
✗ from plotly-stubs.graph_objects import Figure
To use plotly-stubs, simply install it alongside `plotly`. Type checkers will automatically pick up the stub files. The example demonstrates a function that creates a Plotly figure with type hints, leveraging the stubs for static analysis.
import plotly.express as px
import pandas as pd
from plotly.graph_objects import Figure # Type hint for the return
def create_population_chart(df: pd.DataFrame) -> Figure:
"""Creates a population scatter plot using Plotly Express."""
fig = px.scatter(
df,
x="gdpPercap",
y="lifeExp",
size="pop",
color="continent",
hover_name="country",
log_x=True,
size_max=60
)
return fig
# Example usage (assuming 'gapminder' dataset is available, e.g., from px.data.gapminder())
# df_gapminder = px.data.gapminder()
# fig = create_population_chart(df_gapminder)
# fig.show()
Debug
Known issues
gotchaThe `plotly-stubs` package provides *only* type hints. For actual runtime execution of plotting code, the `plotly` library itself must be installed (e.g., `pip install plotly`). `plotly-stubs` does not install `plotly` as a dependency.fixEnsure `plotly` is installed: `pip install plotly`.
affects: All versions
breakingThe `plotly-stubs` package strictly requires Python >=3.11 and <3.15. While the core `plotly` library might support older Python versions, using `plotly-stubs` will enforce this Python version constraint during development and type checking.fixEnsure your development environment uses Python 3.11 or later. Check `python --version`.
affects: All versions
gotchaAs of `plotly-stubs` version 0.1.3, the project is still in 'Beta' development status. This implies that the API for type stubs might evolve, and complete coverage for all `plotly` features may not yet be available or fully stable.fixMonitor the project's GitHub for updates and be prepared for potential changes in type signatures or coverage. Report missing types to the repository.
affects: All versions up to 0.1.3
gotchaWhen using `plotly` with `Dash`, users have reported issues with `Dash` version 3.0 introducing breaking type annotations that do not comply with `mypy`, leading to `Untyped decorator` errors for `dash.callback`. This can indirectly affect the perceived type-completeness when `plotly-stubs` is used in a `Dash` application.fixConsult the `Dash` documentation and community forums for specific workarounds or updates regarding `Dash`'s type annotations. Consider adding `ignore_missing_imports = true` for `dash.*` in `mypy` configuration if issues persist.
affects: Dash 3.x
Upgrade
Version history
0.1.4latest on PyPI · released Aug 24, 2026
Audit
Dependencies
plotlyrequiredThis package provides type stubs for 'plotly'; the 'plotly' library itself is required for actual runtime execution of plotting code.