Web technology based GUI library for desktop applications
Clone or download
Latest commit a21bcd2 Apr 4, 2018
Failed to load latest commit information.
docs Bump version: 0.3.0 → 0.3.1 Mar 5, 2018
profile Improve parser performance and add parser profiling script Aug 10, 2017
.gitignore Update gitignore Aug 27, 2017
.gitmodules Remove rimo submodule. rimo is now part of wdom Sep 13, 2017
.jshintrc Update jshintrc Feb 14, 2018
.travis.yml Skip tests using selenium on Travis Apr 4, 2018
CHANGES.rst Update change log Mar 5, 2018
LICENSE Update copy right May 15, 2016
MANIFEST.in Rename rimo.js to wdom.js Sep 13, 2017
Makefile Update dev env Aug 16, 2017
README.rst Update Readme and example code Aug 8, 2017
dodo.py Change test directory structure Sep 4, 2017
mypy.ini Add mypy config file Jul 25, 2017
requirements-dev.txt Merge duplicated package in setup.py and requirements Feb 14, 2018
requirements-docs.txt Update requirements Aug 8, 2017
requirements-test.txt Change test directory structure Sep 4, 2017
setup.py Bump version: 0.3.0 → 0.3.1 Mar 5, 2018
tox.ini Use unittest on tox Apr 4, 2018



Documentation https://travis-ci.org/miyakogi/wdom.svg?branch=dev https://codecov.io/github/miyakogi/wdom/coverage.svg?branch=dev

WDOM is a python GUI library for browser-based desktop applications. WDOM controls HTML elements (DOM) on browser from python, as if it is a GUI element. APIs are same as DOM or browser JavaScript, but of course, you can write logic codes in python.

This library includes web-server (tornado), but is not intended to be used as a web framework, please use for Desktop GUI Applications.

Document: WDOM Documentation


WDOM is in the early development stage, and may contain many bugs. All APIs are not stable, and may be changed in future release.


  • Pure python implementation
  • APIs based on DOM specification
    • Not need to learn new special classes/methods for GUI
    • Implemented DOM features are listed in Wiki page
  • Theming with CSS frameworks (see ScreenShots on Wiki)
  • JavaScript codes are executable on browser
  • Testable with browsers and Selenium WebDriver
  • Licensed under MIT licence


Python 3.5.3+ and any modern-browsers are required. Also supports Electron and PyQt's webkit browsers.


Install by pip:

pip install wdom

Or, install latest version from github:

pip install git+http://github.com/miyakogi/wdom


Simple example:

from wdom.document import get_document
from wdom.server import start

if __name__ == '__main__':
    document = get_document()
    h1 = document.createElement('h1')
    h1.textContent = 'Hello, WDOM'

Execute this code and access http://localhost:8888 by browser. "Hello, WDOM" will shown on the browser. To stop process, press CTRL+C.

As you can see, methods of WDOM (document.createElement and document.body.appendChild) are very similar to browser JavaScript.

WDOM provides some new DOM APIs (e.g. append for appending child) and some tag classes to easily generate elements:

from wdom.tag import H1
from wdom.document import set_app
from wdom.server import start

if __name__ == '__main__':
    h1 = H1()
    h1.textContent = 'Hello, WDOM'
    set_app(h1) # equivalent to `wdom.document.get_document().body.appendChild(h1)`

Of course, WDOM can handle events:

from wdom.tag import H1
from wdom.document import set_app
from wdom.server import start

def rev_text(event):
    elm = event.currentTarget
    elm.textContent = elm.textContent[::-1]

if __name__ == '__main__':
    h1 = H1('Hello, WDOM')
    h1.addEventListener('click', rev_text)

When string "Hello, WDOM" is clicked, it will be flipped.

Making components with python class:

from wdom.tag import Div, H1, Input
from wdom.document import set_app
from wdom.server import start

class MyApp(Div):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.text = H1('Hello', parent=self)
        self.textbox = Input(parent=self, placeholder='input here...')
        self.textbox.addEventListener('input', self.update)

    def update(self, event):
        self.text.textContent = event.currentTarget.value
        # Or, you can write as below
        # self.text.textContent = self.textbox.value

if __name__ == '__main__':

WDOM package includes some tiny examples. From command line, try:

python -m wdom.exapmles.rev_text
python -m wdom.exapmles.data_binding
python -m wdom.exapmles.timer

Source codes of these examples will be found in wdom/examples.

Theming with CSS Frameworks

WDOM is CSS friendly, and provides easy way to theme your app with CSS frameworks. For example, use bootstrap3:

from wdom.themes import bootstrap3
from wdom.themes.bootstrap3 import Button, PrimaryButton, DangerButton
from wdom.document import get_document
from wdom.server import start

if __name__ == '__main__':
    document = get_document()
        Button('Button'), PrimaryButton('Primary'), DangerButton('Danger')

Differences are:

  • import tag classes from wdom.themes.[theme_name] instead of wdom.tag
  • register theme-module by document.register_theme(theme_module)

If you want to more easily change themes (or, css frameworks), try command-line option --theme. wdom.themes.default module would be switched to --theme option.

For example, in the above code, change from wdom.themes import bootstrap3 to from wdom.themes import default. And execute the code with --theme theme_name option (see below).


Currently, WDOM bundles 20+ CSS frameworks by default, and they are listed in Wiki with screenshots. In each theme module, only primitive HTML elements (typographies, buttons, form components, tables, and grids) are defined, but complex elements like navigations or tabs are not defined.

If your favourite CSS framework is not included, please let me know on Issues, or write its wrapper module and send PR.

Of course you can use your original css. See Loading Static Contents -> Local Resource section in the User Guide.


Contributions are welcome!!

If you find any bug, or have any comments, please don't hesitate to report to Issues on GitHub. All your comments are welcome!

More Documents

Please see User Guide.