Voilà Documentation

The JupyterLab extension is a prebuilt extension. To develop it, you must have the server extension enabled, then link your development version to JupyterLab and build it.

# install the package in development mode
python -m pip install -e .

# link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite

# build the lab extension
jlpm run build --scope @voila-dashboards/jupyterlab-preview

# or use watch mode to pick up changes automatically
jlpm run watch

If a notebook requires user-specific data from a URL query string, pre-rendering might fail. In preheating mode, you can use voila.utils.wait_for_request to pause execution until a user connects, allowing the notebook to capture the QUERY_STRING environment variable.

import os
from voila.utils import wait_for_request

# Pause execution until a user connects and request info is available
wait_for_request()
query_string = os.getenv('QUERY_STRING')

To develop Voilà, create a conda environment with the necessary dependencies, clone your fork, install JS dependencies, and install Voilà in editable mode.

# create a new conda environment
conda create -n voila -c conda-forge notebook jupyterlab nodejs "yarn<4" pip
conda activate voila

# download voila from your GitHub fork
git clone https://github./<your-github-username>/voila.git

# install JS dependencies and build js assets
cd voila
yarn install

# install Voilà in editable mode
python -m pip install -e .

You can install Voilà from PyPI using pip.

pip install voila

Ploomber Cloud offers a free deployment option for Voilà apps:

1. Log in to Ploomber Cloud.
2. Click NEW.
3. Select Voilà in the Framework section.
4. In the Source code section, select Upload your files.
5. Upload your .ipynb file and requirements.txt file.
6. Click CREATE and wait for deployment to finish.

Preheating reduces dashboard load times by maintaining a pool of standby kernels that have already executed the notebook.

Warning: This feature is incompatible with prelaunch-hook functionality.

To activate, set --preheat_kernel=True. You can specify the pool size with --pool_size. For advanced configuration (like per-notebook pool sizes or environment variables), use a voila.json file.

Themes can be applied without CLI flags using these methods:

1. Query Parameter: Append ?theme=<theme-name> to the URL (e.g., http://localhost:8867/voila/render/notebook.ipynb?theme=dark).
2. Notebook Metadata: Set the theme in the notebook file under metadata/voila/theme.

Voilà can be integrated directly into a Jupyter server. To enable it, use the jupyter serverextension enable command for either the notebook or jupyter_server backend. Once enabled, the Voilà app is accessible via the base URL suffixed with /voila.

jupyter serverextension enable voila
# or
jupyter server extension enable voila