Project schedules
Visualize project tasks, milestones, or work packages across calendar dates.
Plotly · Function
px.timeline
px.timeline creates a Plotly timeline in which each data-frame row becomes a horizontal bar spanning start and end dates. It returns a figure with a date x-axis by default and supports categorical or continuous color mapping.
- Since
- 4.9
How it works
px.timeline converts rows in a data frame into horizontal duration bars. Map the start and end columns with x_start and x_end, choose the category axis with y, and optionally map color to another column; the resulting figure uses a date x-axis by default.
Syntax
plotly.express.timeline(data_frame=None, x_start=None, x_end=None, y=None, ...)Parameters
| Name | Type | Description |
|---|---|---|
data_frame | DataFrame | Data frame containing the plotted columns; the reference signature abbreviates the remaining arguments after the initial parameters. |
x_start | str or array-like | Column or array supplying each bar's start date or time. |
x_end | str or array-like | Column or array supplying each bar's end date or time. |
y | str or array-like | Column or array defining the categorical y-axis positions. |
Returns
A Plotly figure representing the timeline.
Key points
- px.timeline was introduced in Plotly 4.9 for constructing timeline and Gantt-style visualizations.
- Each row becomes a horizontal duration bar whose endpoints come from date-valued start and finish fields.
- The x-axis is configured as a date axis by default, making temporal formatting and range controls applicable.
- Color can encode either discrete categories or a continuous numeric measure, depending on the mapped data.
Common mistakes
- Reverse the y-axis when you want the first task listed at the top; the default categorical ordering places tasks from the bottom upward.
- Expect date-axis behavior by default, so date strings or datetime values are interpreted along a temporal x-axis.
Example: Basic project timeline
import pandas as pd
import plotly.express as px
df = pd.DataFrame([
{"Task": "Design", "Start": "2025-01-01", "Finish": "2025-01-10"},
{"Task": "Build", "Start": "2025-01-06", "Finish": "2025-01-20"},
])
fig = px.timeline(df, x_start="Start", x_end="Finish", y="Task")
fig.update_yaxes(autorange="reversed")
fig.show()Creates a timeline in which each task is displayed as a horizontal bar spanning its start and finish dates.
When to use it
Operational durations
Show when jobs, incidents, or processes begin and end.
Resource allocation
Compare resources or categories across overlapping time intervals.
Interview questions
QWhat does px.timeline represent?
It creates a Plotly figure where every data-frame row becomes a horizontal rectangular bar. The bar begins at x_start and ends at x_end, while y identifies the task or category.
Follow-up: How would you show ownership? Map a resource column to color, for example color="Resource", so the bars receive a discrete color category.
QWhich arguments are required for a basic timeline?
Use x_start and x_end to provide the start and finish fields, and y to provide the task field. A minimal call is px.timeline(df, x_start="Start", x_end="Finish", y="Task").
Follow-up: What axis type should be expected? The function defaults the x-axis to date, allowing date-axis configuration such as other time-series charts.
QWhen was px.timeline introduced, and what problem does it address?
The function was introduced in Plotly version 4.9. It is the recommended Plotly Express approach for timeline or Gantt-style charts in the supplied documentation.
Follow-up: What legacy alternative appears in the documentation? The figure-factory create_gantt function is listed as an older option, with px.timeline recommended instead.
Related
plotly.expressplotly.figure_factory.create_ganttpx.linepx.bar