Migrating to Panel UI¶
Skill version 2026.11.12 · 17,071 chars · 2,181 words · 4,414 estimated tokens
This skill provides the steps and diffs for converting an existing plain-Panel app to panel.ui, which requires Panel 1.10 or later.
Start with panel migrate. Panel 1.10 ships a codemod that does the mechanical rewrite (imports, access paths, param names, templates) for you. Run it first, then use the rest of this skill for what it leaves behind. See Automated Pass with panel migrate.
Migration is a presentation change, not a logic change: swap templates, widgets, and panes, but leave every @param.depends, param.watch, pn.bind, and periodic callback untouched. For how the target API works once you're there, see Using Panel UI (Page, layouts, component gotchas, palette, typography, icons). Do not restate those here.
Contents¶
- When to Migrate
- Automated Pass with
panel migrate - Migration Checklist
- Imports and Extension
- Template to Page
- Widgets
- Parameter Names
- Panes
- Layouts
- Styling
- Interaction Upgrades
- Consider New Components
- What Not to Migrate
- Gotchas
- Verifying
When to Migrate¶
- Migrate when the user wants an existing app to use
panel.uior a more modern look. - For a brand-new app, skip this skill and build with Using Panel UI directly.
- Run
panel migratebefore editing by hand. - Do imports + template + widgets together as one coherent pass — a half-migrated app usually won't serve.
- If you find yourself rewriting reactive wiring (
depends,watch,bind), stop: migration changes presentation, not logic.
Automated Pass with panel migrate¶
Panel 1.10 ships a codemod that does the mechanical part of this migration. It needs libcst: pip install "panel[migrate]".
panel migrate app.py src/ # dry run: report only, exits 1 if any file would change
panel migrate app.py --diff # print a unified diff instead of the report
panel migrate app.py src/ --fix # write the changes
It rewrites classic pn.widgets/pn.pane/pn.layout/pn.chat/pn.indicators access paths and bare pn.Row-style shortcuts to pn.ui, name= to label=, button_type/button_style to color/variant, MenuButton(split=True) to SplitButton, and classic templates to pn.ui.Page when every keyword is known to carry over. It removes explicit Panel design selections, rewrites panel_material_ui imports to their pn.ui path, and is a no-op on code that is already migrated.
- Commit or stash first, run with
--diff, read it, then--fix. Run it on the app's own source only; directories are walked recursively, skipping dot directories,venv,build, anddist. - Everything under "manual review" in the report is yours to finish: calls using positional arguments or keywords that don't exist on the
pn.uiclass, templates with keywords that don't map toPage, and designs other than Panel's own. - The codemod knows nothing about this guide's judgment calls. After
--fix, revertpn.ui.Column/pn.ui.Rowon the layout directly wrapping a tile/geo plot (Layouts), check that panes you wanted kept aspn.pane.*(Panes) andGridSpecplacements still make sense, and rewrite anystylesheetsassx(Styling). Walk the rest of the checklist for anything it left, including interaction upgrades and new components. - It reads
*.pyfiles only. - Re-run it after fixing: a clean pass reports nothing and exits 0.
Migration Checklist¶
Walk these in order; each keeps the app runnable. Run the automated pass first and use the list to review what it did and finish what it reported:
- Imports & extension — reference components as
pn.ui.X, droptemplate=. - Template →
pn.ui.Page— collapse template +.servable()calls into one Page. - Widgets —
pn.widgets.X→pn.ui.X;pn.Param(...)→ explicitfrom_param. - Parameter names —
name→label,button_type→color,button_style→variant. - Panes —
pn.pane.Markdown→pn.ui.Typography;pn.pane.Alert→pn.ui.Alert(the only pane swaps). - Layouts —
pn.Row/pn.Column→pn.ui.Row/pn.ui.Columnexcept around tile/geo plots;pn.Card/FlexBox→pn.uiequivalents. - Styling — keep
styles; rewrite anystylesheetsassx. - Interaction upgrades (optional) — replace hand-rolled stateful controls with
panel.uiwidgets, and consider newpanel.uicomponents that may serve better than the pattern you're carrying over. - Verify — serve and screenshot.
Imports and Extension¶
- Import Panel once and reference Material components as
pn.ui.X; there is no separate package import. - Remove
template=frompn.extension(); importingpn.uiselects its Material UI design unless an explicit design was already configured. - Never add
"bokeh"topn.extension(); keep genuine JS extensions ("tabulator","plotly", etc.).
# BEFORE
pn.extension("tabulator", design="material", template="bootstrap", theme="dark")
# AFTER — `pn.ui.Page` replaces the template; `pn.ui` opts into its design
pn.extension("tabulator")
Template to Page¶
- A template plus scattered
.servable()calls collapse into a singlepn.ui.Page. sidebar,main, andheadertake lists — a bare component fails silently.- The title moves to
Page.title. - Dark mode and the light/dark switch are built in — delete manual theme plumbing.
- For Page rules (single-row header, centering, when to skip the sidebar), see Using Panel UI.
# BEFORE — FastListTemplate
tmpl = pn.template.FastListTemplate(title="My App", theme="dark")
tmpl.sidebar.append(controls)
tmpl.main.append(view)
tmpl.servable()
# BEFORE — per-component .servable(area=...)
controls.servable(area="sidebar")
view.servable(title="My App")
# AFTER — one Page
pn.ui.Page(
title="My App",
sidebar=[controls],
main=[view],
theme_toggle=True, # built in — no manual light/dark wiring
).servable()
Widgets¶
panel.uiprovides Material components and re-exports classic components that have no Material equivalent. Swap only when a Material component improves the presentation:pn.widgets.X→pn.ui.X. Usehasattr(pn.ui, "X")to confirm a name.pn.widgets.ButtonIconmaps topn.ui.IconButtonwhen a Material icon button is wanted; otherwisepn.ui.ButtonIconpreserves the classic widget.- Replace an auto-generated
pn.Param(obj.param)panel with explicitui.*.from_param(...)so you control each widget's label, color, and visibility. .from_param()syncs value, bounds, and objects.- Caveat:
.from_param()widgets must be created aftersuper().__init__()— see panel/SKILL.md for the ordering rule. - For which
panel.uiwidget matches each Param type, see Using Panel UI.
# BEFORE — auto-generated widget panel
controls = pn.Param(self.param)
# AFTER — explicit `panel.ui` widgets
self._radius = pn.ui.IntSlider.from_param(self.param.radius, label="Radius")
self._mode = pn.ui.Select.from_param(self.param.mode, label="Mode")
controls = pn.Column(self._radius, self._mode)
Parameter Names¶
panel.ui prefers the new parameter names. Legacy aliases still work, but update them while you're in the code:
| Legacy (Panel) | Modern (panel.ui) |
|---|---|
name= |
label= |
button_type= |
color= |
button_style= |
variant= |
The rename is not mechanical, and neither is assuming a param exists at all — on
RadioButtonGroup/CheckButtonGroup there is no variant to rename to, so the sweep
converts working code into a TypeError. Check with 'variant' in pn.ui.X.param as you go;
the params that trip this are tabled in
Troubleshooting.
Panes¶
- Panes are mostly not migrated — the opposite of widgets.
panel.uiis not a plotting or data-display library, so it ships almost no pane equivalents. - Two swaps are worth making:
- Text:
pn.pane.Markdown→pn.ui.Typography. Typography renders markdown, so headings and bullet lists carry over unchanged; usevariant=(h4,body2, …) for Material text styling. - Alerts:
pn.pane.Alert→pn.ui.Alert. Note:pn.ui.Alertis technically a layout, not a pane — it lives inreference/layouts/, takes positional children like otherpanel.uilayouts (pn.ui.Alert("...", severity="warning")), and can wrap arbitrary content rather than just a string. So you'll find it under Layouts, not Panes, when you look it up. - Everything else can stay
pn.pane.*or move to its re-export inui.*. Preferpn.pane.*for explicit legacy pane types. They drop intopn.ui.Pageanduilayouts untouched, and pick up theme-aware styling automatically inside a Page (see Using Panel UI for plot theming): - Plot panes:
pn.pane.HoloViews,pn.pane.DeckGL,pn.pane.ECharts,pn.pane.Plotly,pn.pane.Matplotlib,pn.pane.Bokeh,pn.pane.Vega. - Media / embed:
pn.pane.Image,pn.pane.Audio,pn.pane.Video,pn.pane.HTML,pn.pane.IFrame. - Data displays:
pn.pane.DataFrame,pn.widgets.Tabulator.
# BEFORE
pn.pane.Markdown("## Overview\n\n- point a\n- point b")
# AFTER
pn.ui.Typography("## Overview\n\n- point a\n- point b")
Layouts¶
pn.Row/pn.Column→pn.ui.Row/pn.ui.Column, so the migrated app uses one namespace. Skip this for the layout directly wrapping a tile/geo plot, which must stay native (tile plot renders blank).pn.ui.Gridis the Material 12-column responsive grid (breakpoint-based), not a drop-in forpn.GridSpec/GridStackcoordinate placement (gspec[0, 0] = ...). Those have no directpanel.uianalog — keep them or rebuild againstpn.ui.Grid's breakpoint model.pn.Card→pn.ui.Card(preferpn.ui.Paperfor plain grouping);pn.FlexBox→pn.ui.FlexBox.pn.Modal/pn.layout.Modal→pn.ui.Dialog(there is nopn.ui.Modal); usepn.ui.Drawerfor a side panel.- Optional: if the existing app nests
pn.*layouts heavily and they work, leave them — migrating layouts is low-value churn. panel.uilayouts take positional args:pn.ui.Paper(a, b), notpn.ui.Paper([a, b]).- Sizing carries over unchanged:
width,height,sizing_mode, andmin_*/max_*work identically on both APIs — copy them across, don't "translate".
# BEFORE
pn.Column(pn.Card(chart, title="Chart"), sizing_mode="stretch_both")
# AFTER — sizing params unchanged
pn.ui.Column(pn.ui.Card(chart, title="Chart"), sizing_mode="stretch_both")
Styling¶
stylescarries over as-is. It styles a component's outer container (spacing, border, background, shadow) and behaves the same on both APIs.stylesheetsdoes not carry over. Classic widgets usestylesheets=[css]to reach internal DOM (.noUi-handle,.noUi-connect) — Panel's Bokeh markup.panel.uirenders entirely different Material UI DOM, so that CSS silently does nothing. Rewrite it assxtargeting MUI slots.- Don't hand-port colors and fonts widget by widget when a single app-wide
theme_configwill do — see Using Panel UI.
# BEFORE — classic Panel, internals via stylesheets
pn.widgets.FloatSlider(
name="Score",
stylesheets=[".noUi-handle { border-radius: 50%; } .noUi-connect { background: #0b6bcb; }"],
)
# AFTER — `panel.ui`, internals via sx + MUI slot selectors
pn.ui.FloatSlider(
label="Score",
sx={
"& .MuiSlider-thumb": {"borderRadius": "50%"},
"& .MuiSlider-track": {"backgroundColor": "#0b6bcb"},
},
)
Interaction Upgrades¶
- Migration is a good moment to replace a hand-rolled stateful control with a purpose-built
panel.uiwidget — but only when it removes code. - Classic case: a play/pause built from a
param.Eventwhose button label you flip manually becomes apn.ui.Toggle, whose booleanvalueis the state, dropping the bespoke_playingflag. - Skip these when they'd complicate things — they're polish, not required for a correct migration.
# BEFORE — Event + manual label/state flipping
play = param.Event(label="▷")
...
def _toggle(self, *_):
if self._playing:
self._cb.stop(); self._btn.name = "▷"
else:
self._cb.start(); self._btn.name = "❚❚"
self._playing = not self._playing
# AFTER — Toggle; value is the state
self._play = pn.ui.Toggle(label="Play", icon="play_arrow")
self._play.param.watch(self._on_play, "value")
def _on_play(self, event):
self._cb.start() if event.new else self._cb.stop()
Consider New Components¶
panel.ui ships components that plain Panel never had. These aren't swaps — there's nothing to replace — but a migration is the natural moment to ask whether a purpose-built component would serve better than the pattern you're carrying over. Reach for them only when they simplify the app; don't add UI for its own sake.
pn.ui.Dialog/pn.ui.Drawer— modal dialogs and slide-out panels. Beyond replacingpn.Modal, aDraweris often a cleaner home for secondary controls than a permanently visible sidebar.pn.ui.Rating,pn.ui.Chip/pn.ui.Pill/pn.ui.MultiPill— first-class inputs for star ratings and tag/selection chips that people otherwise fake with buttons or multi-selects.pn.ui.SpeedDial,pn.ui.SplitButton,pn.ui.Fab— compact action menus and floating actions that replace clusters of buttons.- Navigation menus —
pn.ui.Breadcrumbs/NestedBreadcrumbs,pn.ui.Pagination,pn.ui.Tree,pn.ui.TabMenu,pn.ui.StepperMenu,pn.ui.MenuList— for paged tables, hierarchical data, or multi-step flows previously hand-wired with callbacks. pn.ui.Avatar,pn.ui.Badge,pn.ui.Skeleton,pn.ui.Tooltip— small polish (user chips, count badges, loading placeholders, hover hints).Skeletonis a top-level component;Badge/Tooltip/Transitionapply via the wrapper API rather than as standalone constructors.pn.ui.ThemeToggle,pn.ui.BreakpointSwitcher— standalone versions of behaviorPageexposes viatheme_toggle=True; useful when you're not usingPageor want the control placed manually.
Browse reference/{section}/index.md (especially menus/ and wrappers/, which have no Panel analog) before reimplementing something by hand.
What Not to Migrate¶
Some pn.* objects are re-exported unchanged by panel.ui; keeping their original namespace is clearer:
- Plot / data panes — use
pn.pane.*/pn.widgets.Tabulatorfor the explicit classic names (see Panes for the full list, including media/embed). - Classic widgets and indicators —
panel.uire-exports them, but they retain classic behavior. Usepn.widgets.*orpn.indicators.*when a Material replacement is not intended. - Spacers and low-level layout helpers — keep
pn.layout.HSpacerandpn.layout.VSpacerfor clarity. - All reactive wiring —
@param.depends,param.watch,pn.bind,pn.state.add_periodic_callback.
If unsure whether a panel.ui name exists, confirm with hasattr(pn.ui, "X") or dir(pn.ui), then use Panel's API reference per the Lookup in Using Panel UI rather than guessing a class name.
Gotchas¶
- Duplicate icon.
panel.uibuttons and toggles take a Materialicon=. If you also leave a glyph (▷,❚❚) in the label, you get two icons. Pick one — usually the Materialicon=. - Typography vs Markdown.
pn.ui.Typographyrenders markdown, so swapping headings, labels and KPI text to it is lossless and gainsvariant=styling.pn.ui.Markdown(the classic pane, re-exported) remains fine for long-form prose and reactive text references; don't churn it just to change namespaces. stylesheetssilently no-ops on ui. The CSS targets Panel's old DOM, not MUI slots. Rewrite assx(see Styling);stylesis safe to keep.design='material'is notpanel.ui. It selects Panel's older Material design. Let importingpn.uiselect the new design unless the app deliberately configures another design.- Delete manual dark/light toggles.
Page(theme_toggle=True)replaces them.
Verifying¶
- Use the serve → screenshot → debug loop in Iterating on Panel Apps.