Install & Compatibility
Where this runs
tested against v0.4.1 · 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
436MB installed
● package 436MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
plotly.express
✓ import plotly.express as px
This quickstart demonstrates how to import `plotly.express`, load a sample dataset, create a basic scatter plot with colored data points based on a category, and display the interactive figure.
import plotly.express as px
import pandas as pd
# Use a built-in dataset for a quick example
df = px.data.iris()
# Create a scatter plot
fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species", title="Iris Sepal Width vs Length")
# Display the figure
fig.show()
Debug
Known issues
gotchaThe standalone `plotly-express` PyPI package (version 0.4.1) is now largely a wrapper that re-exports `plotly.express`, which is a module built directly into the main `plotly` library (versions 4.0 and higher). Users typically install `plotly` directly to get `plotly.express`.fixPrefer `import plotly.express as px` after `pip install plotly`. The `plotly-express` package serves mostly for backward compatibility or explicit clarity.
affects: All versions of plotly-express (0.4.1 and earlier), and plotly (4.0+)
deprecatedMapbox-based traces (`scatter_mapbox`, `line_mapbox`, `choropleth_mapbox`, `density_mapbox`) are deprecated in `plotly.py` version 6 and will be removed in a future release. They rely on Mapbox tokens and are being replaced.fixMigrate to Maplibre-based traces such as `scatter_map`, `line_map`, `choropleth_map`, and `density_map` which offer similar functionality without Mapbox dependency.
affects: plotly>=6.0.0
breakingTransforms, which were deprecated in `plotly.py` v5, have been completely removed in `plotly.py` v6. Functionality previously achieved with transforms must now be handled by preprocessing data with a dataframe library.fixRewrite data manipulation logic using pandas, polars, or other dataframe libraries before passing data to Plotly Express functions.
affects: plotly>=6.0.0
breakingSeveral layout attributes for titles (`titlefont`, `titleposition`, `titleside`, `titleoffset`) have been removed in `plotly.py` v6. These were part of the older layout structure.fixUpdate your code to use the new nested title attributes: `layout.title.font`, `layout.title.position`, `layout.title.side`, and `layout.title.offset`.
affects: plotly>=6.0.0
gotchaPlotly Express functions are primarily designed for 'tidy' or long-form dataframes. While some 2D Cartesian functions support wide-form data, using wide-form data may not expose all of Plotly Express's flexible parameter mapping capabilities.fixFor optimal use and to leverage parameters like `color`, `facet_row`, `animation_frame`, etc., it's often best to transform wide-form data into long-form using methods like `df.melt()` from pandas.
affects: All versions
gotchaWhile Plotly Express offers a high-level API for rapid plotting, it provides less fine-grained control over every plot detail compared to `plotly.graph_objects`. For highly customized or complex interactive figures, direct use of `plotly.graph_objects` might be necessary.fixStart with Plotly Express for initial exploration. If specific customizations are not available, you can obtain the figure object from Plotly Express (e.g., `fig = px.scatter(...)`) and then modify it using `fig.update_layout()` or by adding `plotly.graph_objects` traces.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'plotly.express'
The `plotly.express` module is not found, often because the `plotly` library is not installed, is installed in a different environment, or is an older version (pre-4.0) that did not include `plotly.express` as a built-in module. It can also happen if your script is named `plotly.py`, shadowing the actual library.
fixEnsure `plotly` is installed and up-to-date in your active Python environment: `pip install --upgrade plotly`. If your script is named `plotly.py`, rename it.
NameError: name 'px' is not defined
This error occurs when `plotly.express` functions are called using the `px` alias without first importing the module as `import plotly.express as px`.
fixAdd `import plotly.express as px` at the beginning of your script or notebook cell before using `px` functions.
AttributeError: module 'plotly' has no attribute 'express'
This typically means the installed `plotly` library version is too old (prior to version 4.0) to contain the `express` submodule. The standalone `plotly-express` package (version 0.4.1) was integrated into the main `plotly` library as `plotly.express` starting with `plotly` version 4.0.
fixUpgrade your `plotly` library to the latest version: `pip install --upgrade plotly`. Also, uninstall the older `plotly-express` standalone package if it's present: `pip uninstall plotly-express`.
AttributeError: module 'plotly.express' has no attribute 'some_function' (e.g., 'timeline', 'imshow', 'Constant')
You are attempting to use a function or attribute (like `px.timeline` or `px.imshow`) that was introduced in a newer version of `plotly.express` than what you currently have installed, or it doesn't exist.
fixUpgrade your `plotly` library to the latest version to access newer functions: `pip install --upgrade plotly`. If the attribute is `Constant`, it's likely a misunderstanding as `px.Constant` does not exist; check the Plotly Express documentation for the correct way to achieve your goal.
ImportError: Plotly express requires pandas to be installed.
`plotly.express` relies on the `pandas` library for data handling, and this error indicates that `pandas` is not installed in your Python environment.
fixInstall the `pandas` library: `pip install pandas`.
Upgrade
Version history
0.4.1latest on PyPI · released Aug 7, 2019
Audit
Dependencies
plotlyrequiredPlotly Express is now a built-in module within the main Plotly library, `plotly.express`. The `plotly-express` package on PyPI primarily re-exports this functionality.
pandasoptionalCommonly used for data handling with Plotly Express functions, which are optimized for DataFrames.