nicegui 4.0.0

v4.0.0

on Python PyPI

NiceGUI 4.0 is a major release focused on cleaning up: it removes the APIs deprecated during 3.x, corrects a few defaults and catches up on the bundled JavaScript libraries. Nothing changes as fundamentally as the auto-index page did in 3.0, so most apps should only need small adjustments. Some changes don't raise any error, though, so please read the migration guide before upgrading.

How to upgrade

1. Update to the latest 3.19 release, run your app and tests, and fix all deprecation warnings. They name the replacement for most of what is removed in 4.0.
2. Check the new minimum requirements below.
3. Upgrade and run a type checker like mypy or pyright. It flags many leftovers, e.g. sanitize=None, before the first run.
4. Go through the behavior changes below, because most of them won't show up as an error.

New features and enhancements

• Support Python 3.15 (#6394 by @falkoschindler, @evnchn)
• Reduce the memory per connected client by about 14% and another 13% on a measured page, using __slots__ on observable collections and dropping the bindable property registry (#6409, #6410, #6412, #6434 by @evnchn, @falkoschindler)
• Give text inputs a single empty state, so that the value type of ui.input and related elements narrows to str (#6421, #6435 by @falkoschindler, @evnchn, @emmanuelprecieuxargent)
• Add a pagination_controls parameter to ui.table that controls the pagination bar independently of pagination, so that assigning table.pagination later now shows the controls as well, and add on_pagination_change to ui.table.from_pandas and ui.table.from_polars (#6235, #6275 by @evnchn, @SaadZahem, @falkoschindler)
• Use "spawn" as the default start method of the run.cpu_bound process pool, because "fork" is unsafe in a threaded process (#6117, #6419 by @falkoschindler, @evnchn)
• Let run.io_bound and run.cpu_bound keep working in app.on_shutdown handlers and stop them from swallowing task.cancel() (#6420 by @falkoschindler, @evnchn)
• Allow plotly.py 7 for ui.plotly (#6327, #6441 by @falkoschindler, @evnchn)
• Add the Quasar language packs ckb, lb, sr-Cyrl, sq and ur-PK (#6440 by @falkoschindler, @evnchn)

Bugfixes

• Prevent custom Object3D and Layer objects created after an await from landing in another client's scene or map (#6345, #6361, #6401 by @evnchn, @falkoschindler, @wolfgang-aura)
• Fix router pages in app.remove_route() and endpoint_documentation with current FastAPI versions (#6373, #6416 by @falkoschindler, @evnchn, @Melvin0hd)
• Make objects with bindable properties picklable, e.g. as arguments to run.cpu_bound, and stop keeping their classes alive (#6412, #6434 by @evnchn, @falkoschindler)
• Let ui.leaflet add its layers before await map.initialized() returns, so that layer methods no longer return None (#6470 by @falkoschindler)

⚠️ Migration guide

Minimum requirements

• httpx is no longer installed. Apps importing it have to declare it themselves or switch to httpx2, which has the same API. The testing API now uses httpx2 types: User(client: httpx2.AsyncClient), and UserDownload.http_responses and UserDownload.next() hold or return httpx2.Response. In general, please declare every package you import instead of relying on what NiceGUI happens to pull in.
• Python 3.15 on glibc-based Linux needs glibc 2.39 or newer (e.g. Ubuntu 24.04+, Debian 13+) for orjson's wheels. Older systems need a source build with Rust and a C compiler.
• The Docker image now ships pandas 3, polars 2 and numpy 2.5, and no longer includes pytz. Install it yourself or switch to zoneinfo.

Behavior changes

These changes mostly don't raise an error, so your code won't tell you about them.

1. Old prop names are ignored (#6397 by @falkoschindler, @evnchn)

   Snake_case and camelCase prop names are no longer migrated to kebab-case. .props('html_columns=[0]'), for example, now sets a prop nobody reads, so the feature silently stops working and nothing warns about it anymore. Constructor arguments are not affected. Please search your code for the old names:

   All removed prop names

   Element	Old	New
   all elements	resource_path	resource-path
   all elements	dynamic_resource_path	dynamic-resource-path
   ui.aggrid	html_columns	html-columns
   ui.codemirror	highlightWhitespace	highlight-whitespace
   ui.codemirror	lineWrapping	line-wrapping
   ui.colors	dark_page	dark-page
   ui.colors	custom_colors	custom-colors
   ui.echart	enable_3d	enable-3d
   ui.fullscreen	requireEscapeHold	require-escape-hold
   ui.header	add_scroll_padding	add-scroll-padding
   ui.leaflet	draw_control	draw-control
   ui.leaflet	hide_drawn_items	hide-drawn-items
   ui.leaflet	additional_resources	additional-resources
   ui.markdown	resource_name	resource-name
   ui.markdown	use_mermaid	use-mermaid
   ui.scene	background_color	background-color
   ui.scene	click_events	click-events
   ui.scene	drag_constraints	drag-constraints
   ui.scene, ui.scene_view	camera_params	camera-params
   ui.scene, ui.scene_view	camera_type	camera-type
   ui.scene, ui.scene_view	show_stats	show-stats
   ui.scene_view	scene_id	scene-id

2. Cleared text inputs hold '' instead of None (#6421, #6435 by @falkoschindler, @evnchn, @emmanuelprecieuxargent)

   This affects ui.input, ui.textarea, ui.date_input, ui.time_input and ui.color_input. Replace value is None with not value, which works before and after. A model using None as "empty" can keep it with input.bind_value(model, 'x', forward=lambda v: v or None, backward=lambda v: v or ''). ui.number and ui.select keep None.

3. run.cpu_bound uses "spawn" by default (#6117, #6419 by @falkoschindler, @evnchn)

   Workers start from a fresh import and don't inherit module globals. The function must be importable in the worker: functions defined under if __name__ == '__main__':, via python -c, stdin, a zipapp or a package's __main__.py now fail with BrokenProcessPool, and the actual error only appears in the worker's log. To keep the old behavior on Linux, set run.process_pool_start_method = 'fork' before ui.run().

4. run.io_bound and run.cpu_bound raise asyncio.CancelledError instead of returning None (#6420 by @falkoschindler, @evnchn)

   Code checking if result is None: to detect a shutdown or cancellation has to catch the exception or let it propagate.

5. Element IDs in the DOM change from c12 to ng-12 (#6375, #6378, #6395 by @falkoschindler, @evnchn)

   Replace hard-coded IDs in CSS, JavaScript or tests with element.html_id or getHtmlElement(element.id). Custom components stripping the prefix with id.slice(1) have to use parseHtmlId(id). The implicit browser globals like c12 are gone, and the global of ui.scene for Selenium tests is now scene_<id>.

6. Spot lights in ui.scene default to decay=2.0 (#6243, #6366, #6417 by @falkoschindler, @evnchn, @python-and-novella)

   They now fall off like in Three.js with 1/r² instead of 1/r, so at a distance of 5 units they are five times dimmer. Pass decay=1.0 to restore the old look, or increase intensity.

7. table.pagination shows the pagination controls (#6235, #6275 by @evnchn, @SaadZahem, @falkoschindler)

   This also applies to tables created without pagination, and .props('hide-pagination') no longer survives a later assignment. Use pagination_controls=False instead.

8. Custom scene objects and map layers need a with block in handlers and timers (#6345, #6361, #6401 by @evnchn, @falkoschindler, @wolfgang-aura)

   Constructing a custom Object3D or Layer subclass outside of with scene: used to find the last scene or map touched anywhere in the process. Now it raises a RuntimeError. The same applies to on_click=scene.box, which fetches the constructor early: use on_click=lambda: scene.box(). Object3D.current_scene and Layer.current_leaflet are now private.

9. Screen.should_not_contain waits for the text to disappear (#6432 by @falkoschindler, @evnchn)

   It used to fail immediately if the text was still shown, and then observed for 0.5 s. A check that something must not show up after an action now needs duration=0.5 to keep its strength. The parameter wait is a deprecated alias for duration.

10. Observable collections have no __dict__ (#6409, #6410 by @evnchn, @falkoschindler)

    vars() and setting arbitrary attributes fail on ObservableDict, ObservableList, ObservableSet and on element.props, classes and style. Subclasses without their own __slots__, like PersistentDict, are not affected.

11. Bindings no longer poll bindable properties written past BindableProperty.__set__ (#6412, #6434 by @evnchn, @falkoschindler)

    This only concerns values set via __dict__.update, a custom __copy__ or a descriptor subclass that skips super().__set__. Regular assignments still propagate.

12. WEB_CONCURRENCY above 1 raises a ValueError (#6467 by @falkoschindler)

    NiceGUI doesn't support multiple workers. With reload=True, the default, uvicorn used to ignore the variable with a warning, and with reload=False, the app logged a message and exited. Please remove the variable from the environment of your app.

13. ui.timer callbacks must not swallow the cancellation (#6470 by @falkoschindler)

    A callback catching asyncio.CancelledError without re-raising it can delay the shutdown, which 3.19 tolerated. run.io_bound and run.cpu_bound no longer do this themselves (#6420), so this only concerns your own code.

Removed APIs

These fail with an error or are flagged by a type checker (#6397 by @falkoschindler, @evnchn):

ui.codemirror(language='Jinja2') still works, but is deprecated and logs a warning. Please use language='Jinja' (#6467 by @falkoschindler).

Bundled libraries

If you use these elements, or target their internals with custom CSS or JavaScript, please check the respective changes:

Dependencies

• Update the remaining Python and JavaScript dependencies, including uvicorn 0.54, Starlette 1.10 and websockets 17 in the lock file (#6467 by @falkoschindler)

  Other JavaScript dependencies

  • @tailwindcss/browser: 4.1.13 → 4.3.4
  • @unocss/reset and @unocss/runtime: 66.6.0 → 66.12.0
  • socket.io: 4.8.1 → 4.8.4
  • vue: 3.5.22 → 3.5.44
  • @codemirror/language-data: 6.5.1 → 6.5.2
  • @uiw/codemirror-themes-all: 4.25.2 → 4.25.12
  • @babel/runtime: 7.28.4 → 7.29.10
  • vanilla-jsoneditor: 3.10.0 → 3.13.0
  • mermaid: 11.16.1 → 11.17.2
  • d3-transition: 3.0.2 (new)
  • sass: 1.94.0 (removed)

Documentation

• Fix the docstring markup, which rendered code in italics, and check docstrings in pre-commit (#6451 by @falkoschindler, @evnchn)

Testing

• Speed up the test suite and add Screen.SCREENSHOT_PASSED_TESTS to skip screenshots of passed tests (#6432 by @falkoschindler, @evnchn)
• Let Screen.start_server() wait until the server accepts connections (#6398 by @falkoschindler, @evnchn)

Infrastructure

• Update the development tooling, including mypy 2, isort 9 and Ruff 0.17 (#6450 by @falkoschindler, @evnchn)

Special thanks to our top sponsors DiscoLike Inc., TestMu AI and Lechler GmbH ✨

and all our other sponsors and contributors for supporting this project!

🙏 Want to support this project? Check out our GitHub Sponsors page to help us keep building amazing features!