A Sankey diagram shows where a quantity comes from, where it goes, and how it splits between destinations. Its connecting bands change width according to the amount they represent, making the largest flows easy to spot.
Think about customers making repeat purchases. Some place another order, while others have no further purchase recorded. A Sankey diagram shows those branches together, then follows the returning group to the next purchase milestone.
The same approach works for electricity generation, financial allocations, and material flows. What makes a Sankey useful is the relationship between stages. When the data is prepared correctly, we can trace a quantity through the diagram and account for where it ends up.
That last part matters. A wide ribbon can be persuasive, but it doesn't tell us whether the underlying records were counted correctly. We'll use interactive Sankey diagrams built in Deepnote to explore these relationships with real data, from customer journeys to electricity generation and public spending.
What is a Sankey diagram?
A Sankey diagram is a flow visualization in which the width of each connecting band is proportional to a numerical quantity. You may also see it called a Sankey chart.
The diagram connects sources, intermediate stages, and destinations. A source may split into several paths, and multiple paths can converge on the same destination.
Suppose we're following customers through successive purchases. Some make another purchase, while others have no additional order in the observation period.
The diagram begins with 4,338 customers who made at least one qualifying purchase. Of those, 2,845 made at least two purchases and 1,493 had no second purchase recorded.
The 2,845 returning customers then split into another two groups: 2,010 made at least three purchases, and 835 had no third purchase recorded.
Every customer is accounted for at each stage.
The connecting bands make those outcomes visible. A wider band represents more customers, so readers can follow the main path without inspecting every number individually.
Why Sankey diagrams need consistent quantities
The quantities entering and leaving a stage should reconcile whenever the diagram represents a conserved total.
In the customer example, each split accounts for the full group entering that stage:
Stage | Continued | No next purchase recorded | Total entering the stage |
|---|---|---|---|
From one to two purchases | 2,845 | 1,493 | 4,338 |
From two to three purchases | 2,010 | 835 | 2,845 |
The two outcomes in each row add up to the group entering that stage.
If a diagram begins with 4,338 customers but only accounts for 2,845, readers need to know what happened to the remaining 1,493.
A flow may legitimately leave the system, be consumed, or become a final output. It shouldn't disappear because the chart omitted an inconvenient category.
For energy diagrams, quantities must also use consistent units and account for relevant losses. For financial diagrams, the inflows and outflows must follow the accounting definitions used by the source data.
Sankey diagram key components & parts
A Sankey diagram combines nodes, connecting links, and numerical values. Its layout and labels explain what those connections represent.
Nodes in a Sankey diagram
Nodes represent the stages, categories, or entities connected by the flows.
In a customer journey, nodes might include visits, signups, purchases, and exits. In an electricity diagram, they might represent energy sources, generation technologies, and outputs.
A node may receive several incoming links, send quantities along several outgoing links, or both.
A final node can represent an endpoint, such as a completed purchase, discarded material, or a category of expenditure.
Links and ribbon widths in a Sankey diagram
Links are the bands connecting nodes. Each link has a source, destination, and value.
The wider the link, the larger the represented quantity.
For example, our repeat-purchase diagram has a link of 2,845 customers moving from the first-purchase cohort to the second-purchase cohort. The separate link of 1,493 represents customers without another observed order.
Because both use the same unit, we can compare their widths meaningfully.
Colors can help distinguish categories or pathways, but the widths should carry the numerical information.
Direction and stages in a Sankey diagram
Sankey diagrams are often arranged from left to right, although other layouts are possible.
The direction should match the relationship being represented. For a customer funnel, that may be the order of events. For a budget allocation, it may be the progression from a total to spending categories.
The columns aren't necessarily points in time.
A Sankey showing expenditure by department describes an accounting breakdown. It doesn't imply that money physically passes through every node in sequence.
Labels and units in a Sankey diagram
Each link should represent a well-defined quantity.
A chart showing 500 users, $500 in revenue, and 500 kilowatt-hours on the same width scale would be meaningless.
Choose a consistent measure for each Sankey. If the source data contains different units, convert them where appropriate or separate the analyses.
For interactive charts, hover labels should show the source, destination, value, and unit. Readers shouldn't have to guess whether a band represents people, transactions, dollars, or energy.
Sankey diagram use cases
Use a Sankey diagram when the connections between stages matter as much as the amounts.
Use case | Question it can answer | Quantity to track |
|---|---|---|
Customer journeys | How many customers reach the next stage, and where do others stop? | Distinct customers |
Budget allocations | How is a total divided among departments and spending categories? | Money in one currency |
Energy balances | How do energy inputs become useful outputs and losses? | Energy in consistent units |
Material flows | How much material becomes a finished product, waste, or recycled output? | Mass or volume |
Transfers between groups | How many accounts move between subscription plans? | Distinct accounts |
Use a consistent population, period, and unit throughout. For customer journeys, define how long each customer has to reach the next stage. For a resource balance, account for outputs and losses so the quantities reconcile.
If the question is simply which category has the largest total, a bar chart is usually easier to read.
How to read a Sankey diagram
Start with the source, follow the widest paths, and check what happens at each split.
1. Identify what is flowing
Before interpreting any ribbon, read the title and units.
In the repeat-order example, the quantity is distinct customers. A customer appears once in the starting cohort, even if they placed many orders.
That's different from counting transactions. A single customer might contribute several transactions, but we aren't treating each transaction as a separate person.
2. Follow one path through the diagram
Start with a source node and trace its outgoing bands.
Our first-purchase cohort splits into customers with another recorded order and customers without one. From the returning group, follow the next split to see who reached a third purchase.
A Sankey becomes easier to read when you follow one path at a time. Trying to compare every ribbon simultaneously is especially difficult in a large diagram.
3. Compare the widths
Wider links indicate greater quantities.
In our retail example, the band leading to a second purchase is wider than the band showing no second order recorded. More customers fall into the first group.
But width alone isn't enough for close comparisons. Use the hover values or labels when the numerical difference matters.
4. Look for splits, merges, and exits
Splits show how a quantity is divided. Merges show quantities from multiple sources arriving at the same destination.
Exits need particular attention.
In an acquisition funnel, someone may leave before signing up. In a production process, material may become waste. In an energy system, some input energy may become waste heat.
Represent those outcomes explicitly when they're part of the analysis.
Our retail data has another limitation: it ends on December 9, 2011. A customer without a subsequent recorded order might have purchased again after that date.
We therefore call the exit no further purchase observed, not churn.
5. Check whether the totals balance
At each intermediate node, ask whether the incoming and outgoing values reconcile.
Some Sankey layouts allow nodes with unequal inflows and outflows, which may be appropriate for specific models. But unexplained differences in a conserved flow are a warning sign.
Check the original data before interpreting those differences as losses or gains.
Sankey diagram vs. alluvial diagram
Sankey and alluvial diagrams look similar because both use bands whose widths represent quantities.
Their analytical purposes differ.
A Sankey diagram typically emphasizes quantities flowing through a network. The nodes may represent processes, resources, destinations, or other connected entities. Its structure can branch and merge through several stages.
An alluvial diagram emphasizes how observations are distributed across categories or change membership between successive categorical dimensions.
For example, suppose we have survey responses from the same customers in January and June. We want to see who remained on the same subscription tier and who moved to another.
An alluvial diagram could place January plans in the first column and June plans in the second, with bands representing the number of customers belonging to each combination.
The observations needn't describe a physical flow. The bands show how the same population is classified across two measurements.
Two fictional examples: the Sankey diagram traces budget allocations, while the alluvial diagram shows customers’ subscription plans at two dates. Band widths represent dollars on the left and customer counts on the right.
That distinction also explains why an alluvial diagram is useful for categorical data with no natural sequence of transfers. It can show how the same records are grouped by region, customer type, and subscription plan.
The terms sometimes overlap in charting libraries and product interfaces. The important question is what each band represents.
If we're tracing energy, money, materials, or users through stages, Sankey terminology generally fits. If we're showing transitions or relationships among categorical classifications, an alluvial diagram may be more precise.
Sankey diagram examples with real data
The following examples use published datasets. Each demonstrates a different type of flow and a different constraint on how we should interpret it.
Example 1: Customer progression through repeat purchases
The UCI Online Retail dataset contains transactions from a UK-based retailer between December 2010 and December 2011.
We excluded canceled transactions, records without customer IDs, and line items with nonpositive quantities or prices. We then counted distinct invoices for each identified customer.
The resulting cohort contains 4,338 customers with at least one qualifying purchase.
Follow the main path: 2,845 of the 4,338 customers made at least two qualifying purchases, and 2,010 made at least three. The side branches account for customers without another recorded purchase at each stage.
These are purchasing milestones within the dataset, not necessarily the customers’ first-ever orders. The records also end on December 9, 2011, so an exit means no next purchase was observed before that date, not confirmed churn.
Customers who first appear near the end of the dataset have less time to return. A retention analysis would need comparable follow-up periods before using these counts to compare customer groups.
Example 2: Electricity generation by source
Sankey diagrams have a long history in energy analysis because they can show how energy enters a system, moves through processes, and becomes useful output or loss.
For a real-data example, we used the US Energy Information Administration's Electric Power Annual, selecting six utility-scale electricity generation sources for 2024.
The sources are natural gas, coal, nuclear, wind, conventional hydroelectric power, and solar.
The selected sources contribute approximately 4,218.6 terawatt-hours of net electricity generation.
Natural gas is the largest of these six sources, contributing approximately 1,869.9 TWh. Nuclear contributes about 781.9 TWh, followed by coal at 652.2 TWh.
The diagram groups the sources into fossil and low-carbon categories before combining their net generation.
This is an accounting breakdown, so we need to be careful with the word flow. The chart does not show where electricity traveled on the grid or how much primary energy entered the generating facilities.
A full energy-flow Sankey could trace fuel inputs into conversion processes, with useful electricity and conversion losses represented separately. That would require additional data and consistent energy units.
Our diagram answers a narrower question: how much net electricity generation came from the six selected sources?
It doesn't represent every electricity source in the United States.
Example 3: Federal budget outlays by function
Sankey diagrams are also useful for explaining financial allocations.
The US Treasury's FY2024 Combined Statement reports approximately $6.75 trillion in federal outlays.
We grouped the reported spending into major functional categories and consolidated the remaining functions into an "Other" category.
Social Security accounts for approximately $1.46 trillion. Health, Medicare, national defense, and net interest each represent substantial portions of the total.
The Sankey makes the relative sizes of those categories visible. It also preserves the overall spending total.
There is an accounting distinction here. These figures are actual outlays recorded for fiscal year 2024, not a proposed budget or a forecast.
The diagram also doesn't trace dollars from particular taxes to specific government programs. Federal receipts and spending aren't linked that way in this analysis.
If we wanted to compare the exact spending amounts across functions, a bar chart would be easier to scan.
The Sankey communicates the allocation of the total. The bars make the differences between individual categories more precise.
When these examples are useful
The retail diagram tracks a cohort through successive observed milestones. The electricity diagram groups measured generation quantities. The budget diagram divides a reported financial total into expenditure categories.
They share the same visual structure, but they require different assumptions.
That is why we recommend deciding what the links mean before generating the chart. A diagram can be visually coherent while describing an accounting relationship, a classification, or an observed sequence of events. Those interpretations shouldn't be mixed.
Libraries for creating Sankey diagrams
Several libraries can turn flow data into a Sankey diagram. The right choice depends on whether you want an interactive notebook chart, a static figure, or a custom web visualization.
Library | Environment | Useful for | Input approach |
|---|---|---|---|
Python | Interactive notebook charts with hover values and configurable nodes and links | Node labels plus source indices, target indices, and link values | |
Python | Building Sankeys from tabular data, with interactive rendering through Bokeh | Source-target-value records, with optional node information | |
Python | Static flow-balance figures within an existing Matplotlib workflow | Signed inflow and outflow values, labels, and connections between subdiagrams | |
JavaScript | Custom web visualizations with control over rendering and interaction | Node and link objects for a directed network without cycles | |
JavaScript | Browser-based Sankeys with automatic layout | A table containing source, destination, and weight |
For the customer example in this article, Plotly provides the interactive diagram while Python prepares and checks the customer counts. Deepnote keeps those calculations and the visualization together in a notebook.
A library draws the supplied flows; it does not establish that they were counted correctly. Check the units, membership rules, and stage totals before adjusting the layout.
Google Charts is a JavaScript visualization library, separate from the chart menu in Google Sheets.
How to make a Sankey diagram
To create a Sankey diagram, prepare a table containing the source, target, and value for every flow. The charting tool then converts those records into nodes and proportional-width links.
Make a Sankey diagram with Deepnote Agent
In Deepnote’s Sankey diagram generator, describe the source data, counting rules, and flows in one request. Agent can prepare the source-target-value table before drawing the diagram.
For this example, ask Agent to load the public UCI Online Retail dataset and calculate the repeat-purchase stages:
Load the UCI Online Retail dataset, dataset ID 352, using Python. Retrieve the original records, including CustomerID, InvoiceNo, InvoiceDate, Quantity, and UnitPrice. Use the official UCI download if the library loader does not include the invoice identifiers.
Exclude records without CustomerID, invoices whose numbers begin with C, and line items with nonpositive Quantity or UnitPrice. Count distinct InvoiceNo values for each customer after filtering; do not count product rows as separate orders.
Calculate the number of customers with at least one, at least two, and at least three qualifying purchases. Create these flows:
Use distinct customers as the unit throughout. Verify that each pair of outgoing flows sums to the number entering that stage. Show the source-target-value table and balance checks.
Create an interactive Plotly Sankey arranged from left to right. Show the source, destination, and customer count on hover. Title it “Observed repeat purchases in UCI Online Retail.” Include the observation period and explain that these are recorded purchasing milestones, not confirmed churn or first-ever customer purchases.
Report the calculated counts rather than substituting expected values. Flag that customers appearing later in the dataset have less time to make another purchase.
With the filtering rules used in this article, the expected milestone counts are 4,338 customers with at least one purchase, 2,845 with at least two, and 2,010 with at least three. If a new run differs, inspect the source and filtering steps before interpreting the diagram.
A follow-up request can make the checks easier to review:
Add a table showing the customers entering each stage, those continuing, and those with no next purchase observed. Include a balance-check column. Keep the counting rules and chart values unchanged.
The notebook keeps the record filtering, order counts, and flow calculations alongside the visualization, so teammates can inspect how each link was produced.
Can you make a Sankey diagram in Excel?
Deepnote offers a more direct workflow for preparing flow data and generating the diagram together. Excel can still organize the source records and calculate the flow table, but it does not provide a standard built-in Sankey chart.
Excel-based options include third-party add-ins or custom constructions. Our guide to making a Sankey diagram in Excel explains those approaches and demonstrates the Deepnote alternative.
Common Sankey diagram mistakes
Showing too many nodes
A Sankey with dozens of small nodes can become difficult to navigate.
Readers may struggle to identify the main paths, especially when many links converge or split repeatedly.
Start with the most important stages. Combine minor categories only when the grouping remains analytically valid and clearly labeled.
If users need the complete detail, an interactive diagram can provide hover values while keeping the initial view manageable.
Allowing links to cross unnecessarily
Crossing ribbons make it harder to follow individual paths.
Reorder nodes so the most important flows move through the chart with fewer crossings. Group related destinations together when possible.
Don't reorder stages in a way that changes their meaning merely to produce a cleaner image.
Mixing different units
A Sankey should not compare customers, orders, and revenue as though they were interchangeable quantities.
One customer may generate several orders, and an order may contain multiple items.
Decide what a link counts and use that measure consistently throughout the diagram.
If you need to analyze several measures, produce separate charts or use clearly distinguished views.
Adding every link as though it represents a new quantity
A customer or resource can pass through more than one link. Adding all link values therefore does not necessarily give the number of customers or the amount entering the system.
In the retail example, customers who reach a second purchase are counted again as they move toward a third purchase or its exit branch. The starting cohort remains 4,338 customers.
Use the source total to describe the starting quantity and check each stage separately.
Hiding exits or unexplained differences
In customer funnels, a missing exit branch may make it appear that the entire starting cohort continued to the next stage.
In energy analyses, failing to represent losses may imply perfect conversion efficiency.
Account for meaningful departures, outputs, and losses using the definitions supported by the source data.
Treating every connection as a physical transfer
A budget Sankey may show spending divided among functions. That doesn't mean money physically moved through each category in the displayed order.
Likewise, a Sankey connecting customer characteristics may represent categorical relationships instead of sequential events.
Label the diagram according to what the links describe.
Using a Sankey when another chart is clearer
A Sankey earns its space when the connections are part of the question.
If you only want to compare how much revenue each department generated, use the bar graph maker. Bars make individual category values easier to compare.
If you want to examine how total revenue changed every month, use the line graph maker. A line keeps the sequence and trend visible.
Sankey diagrams can become elaborate very quickly. We shouldn't make readers trace ribbons when a few aligned bars would answer the question.