Voilà can be used as a standalone application, or as a Jupyter server extension. This page describes how to do each. Before you begin, make sure that you follow the steps in Installing Voilà.
The following sections cover how to use Voilà.
As a standalone application¶
Voilà can be used to run, convert, and serve a Jupyter notebook as a standalone app. This can be done via the command-line, with the following pattern:
voila <path-to-notebook> <options>
For example, to render the
bqplot example notebook as a standalone app, run
git clone https://github.com/voila-dashboards/voila cd voila voila notebooks/bqplot.ipynb
Voilà displays a message when your notebook-based application is live.
By default, Voilà runs at
To serve a directory of Jupyter Notebooks, navigate to the directory
you’d like to serve, then simply run
cd notebooks/ voila
The page served by Voilà will now contain a list of any notebooks in the directory. By clicking on one, you will trigger Voilà’s conversion process. A new Jupyter kernel will be created for each notebook you click.
As a Jupyter server extension¶
You can also use Voilà from within a Jupyter server (e.g., after running
jupyter lab or
To use Voilà within a pre-existing Jupyter server, first start the server, then go to the following URL:
For example, if you typed
jupyter lab and it was running at
http://localhost:8888/lab, then Voilà would be accessed at
In this case, Voilà will serve the directory in which the Jupyter server was started.
How does Voilà work?¶
When Voilà is run on a notebook, the following steps occur:
Voilà runs the code in the notebook and collects the outputs
The notebook and its outputs are converted to HTML. By default, the notebook code cells are hidden.
This page is served either as a Tornado application, or via the Jupyter server.
When users access the page, the widgets on the page have access to the underlying Jupyter kernel.
The example notebooks¶
The notebooks directory contains a collection of Jupyter notebooks that can be rendered using Voilà:
basics.ipynb - a notebook with interactions requiring a roundtrip to the kernel.
bqplot.ipynb - uses custom Jupyter widgets such as bqplot.
dashboard.ipynb - uses gridstack.js for the layout of each output.
gridspecLayout.ipynb - uses GridspecLayout for the layout of different widgets.
interactive.ipynb - makes use of ipywidget’s @interact.
ipympl.ipynb - contains custom interactive matplotlib figures using the ipympl widget.
ipyvolume.ipynb - uses custom Jupyter widgets such as ipyvolume.
query-strings.ipynb - uses HTTP query parameters to parametrize a notebook
xleaflet.ipynb - a notebook that uses C++ kernel and interactive widgets
These examples demonstrate different interactive HTML widgets and can be used as inspiration for getting started with Voilà.
To run the example notebooks, a few additional libraries can be installed using:
conda install -c conda-forge ipywidgets ipyvolume bqplot scipy
conda env create
The examples can then be served with:
cd notebooks/ voila
Using third-party Widgets with Voilà¶
By default, Voilà doesn’t serve Jupyter Widgets installed as a classic notebook extension (nbextension).
Instead, it fallbacks to fetching the files from a CDN. This might result in an error (404) in case the
custom widget has not been published to
npm, or when Voilà runs in an environment without an Internet
To let the Voilà standalone app serve the nbextensions, use the
enable_nbextensions flag as follows:
When using Voilà as a server extension:
jupyter notebook --VoilaConfiguration.enable_nbextensions=True