Reference for flexx.webruntime

Webruntime introduction

The webruntime module can be used to launch a runtime for applications based on HTML/JS/CSS. This can be a browser or something that looks like a desktop app.

Supported runtimes

Here’s a quick overview of the supported runtimes. For details, see the docs of the runtime classes below.

  • xul - Mozilla’s app framework. Available wherever Firefox is installed. Recommended.
  • nwjs - An app runtime based on Chromium and node.js.
  • pyqt - Use QWebkit as a runtime. Need PyQt4 or PySide with QWebkit installed.
  • chromeapp - Native-ish looking apps via Chrome/Chromium.
  • browser - The default browser.
  • browser-X - Where X should be supported by Python’s webbrowser module.
  • selenium-X - Where X should be supported by Selenium.
  • nodejs - A runtime based on Chrome’s V8 JavaScript engine. No UI.

Runtimes currently not supported:

  • mshtml - uses the trident engine (like IE does), I think we want this one.
  • electron - by github (, based on Chromium)

Memory considerations

  • xul uses one process, taking about 45 MB app
  • pyqt uses one process, taking about 48 MB per app
  • chrome uses 4 process plus 3 per app, taking 100 MB plus 74 per app
  • MSHTML todo

Webruntime API

flexx.webruntime.launch(url, runtime=None, **kwargs)

Launch a web runtime in a new process.

  • url (str) – The url to open. To open a local file prefix with file://.
  • runtime (str) – The runtime to use. Can be ‘xul’, ‘nwjs’, ‘pyqt’, ‘chromeapp’, ‘browser’, ‘browser-X’, ‘selenium-X’, ‘nodejs’. By default uses ‘xul’ if available, and ‘browser’ otherwise.
  • kwargs – addition arguments specific to the runtime. See the docs of the runtime classes.

runtime – An object that can be used to control the runtime to some extend.

Return type:


class flexx.webruntime.BaseRuntime(**kwargs)

Base class for all runtimes.


Close the runtime, or kill it if the process does not respond. Note that closing does not work when the runtime is a browser, because we need a process handle.

class flexx.webruntime.DesktopRuntime(**kwargs)

A base class for runtimes that launch a desktop-like app.

  • title (str) – Text shown in title bar.
  • size (tuple of ints) – The size in pixels of the window.
  • pos (tuple of ints) – The position of the window.
  • icon (str | Icon) – Icon instance or path to an icon file (png or ico). The icon will be automatically converted to png/ico/icns, depending on what’s needed by the runtime and platform.
class flexx.webruntime.XulRuntime(**kwargs)

Desktop runtime based on Mozilla’s XUL framework. Xul is available wherever Firefox is installed, and uses same engine (Gecko). Requires Firefox or the Xul binaries to be installed.

This runtime is currently the best supported way to create a desktop app, with full support for title, window position, icon and custom process name.

class flexx.webruntime.NodeWebkitRuntime(**kwargs)

Desktop runtime for nw.js (, formerly node-webkit), which is based on Chromium and nodejs. Requires nw.js to be installed.

class flexx.webruntime.PyQtRuntime(**kwargs)

Desktop runtime based on qt-webkit. Launches a new Python process (the same version as the current), and uses PyQt4 or PySide to display the page.

class flexx.webruntime.ChromeAppRuntime(**kwargs)

Desktop runtime based on chrome app. Requires the Chrome or Chromium browser to be installed.

Note: icon, sizing and title is not yet supported.

class flexx.webruntime.BrowserRuntime(**kwargs)

Runtime based on the Python webbrowser module. For Firefox, Chrome and Chromium the runtime can often be loaded even if Python’s webbrowser module cannot.

class flexx.webruntime.SeleniumRuntime(**kwargs)

Runtime based on Selenium (, a tool to automate browsers, e.g. for testing. Requires the Python package “selenium” to be installed.


The Selenium webdriver object. Use this to control the browser.

class flexx.webruntime.NodejsRuntime(**kwargs)

Runtime for nodejs ((, which is based on Chrome’s V8 JavaScript engine. No UI, for computations and testing only. Requires nodejs to be installed .

The uri argument is not used in the same way as in the other runtimes, because nodejs does not deal with HTML. The uri is only used to create a location object for compatibility with browsers.

Parameters:code (str) – The code to run.