Voila

Common errors

• Jupyter command 'voila' not found.

  cause Voila is not installed, or its executable entry point is not in the system's PATH, or the active Python environment does not have Voila installed.
  fix Ensure Voila is installed in your active environment (`pip install voila` or `conda install -c conda-forge voila`). Verify that the environment's `bin` (Linux/macOS) or `Scripts` (Windows) directory is correctly added to your system's PATH.

• ModuleNotFoundError: No module named 'voila'

  cause The `voila` Python package is not installed in the currently active Python environment.
  fix Install the package using your package manager: `pip install voila` or `conda install -c conda-forge voila`.

• Error displaying widget: model not found

  cause This typically indicates a mismatch between the `ipywidgets` version in your notebook and the frontend assets available to Voila, or a missing JupyterLab extension for a custom widget.
  fix Ensure `ipywidgets` is up-to-date (`pip install -U ipywidgets`). For custom widgets, verify that necessary JupyterLab extensions are installed and built (`jupyter labextension install <package>`). Sometimes, a browser cache clear is also helpful.

• voila: error: argument --enable_nbextensions: invalid choice: 'True'

  cause This error occurs when using a command-line argument or configuration option that has been removed or renamed in a newer version of Voila (e.g., `--enable_nbextensions` was removed in Voila 0.5.x).
  fix Consult the official Voila documentation or the `--help` output of your specific Voila version (`voila --help`) to identify valid command-line arguments and remove or update any deprecated options.

Warnings

• breaking Earlier versions of Voila (e.g., prior to 0.4.5 and 0.5.8) had reduced compatibility with `ipywidgets 7`, potentially causing existing notebooks to fail if they relied on older widget versions. Newer releases re-added support.
  Fix: Upgrade to Voila 0.4.5+ or 0.5.8+ for improved ipywidgets 7/8 compatibility. Ensure your `ipywidgets` package is also up-to-date (`pip install -U ipywidgets`).
• gotcha Some Voila templates or custom JupyterLab extensions (e.g., for specific widget packages) may require `nodejs` and `npm` to be installed on your system for building frontend assets. These are not direct Python dependencies.
  Fix: If encountering issues with frontend rendering or custom templates, install Node.js and npm (`conda install -c conda-forge nodejs` or via system package manager) and potentially build extensions (`jupyter labextension install ...`).
• gotcha Multiple older versions contained a security vulnerability (CVE-2024-30265) related to arbitrary file read. Running outdated versions in production environments is risky.
  Fix: Upgrade Voila to at least version 0.3.8, 0.4.4, or 0.5.6 (or newer) to mitigate this vulnerability.
• gotcha Versions of Voila in the 0.5.x series (e.g., 0.5.9, 0.5.10, 0.5.11) included fixes for server extension configuration handling. Users with complex custom `voila_config.py` files might experience unexpected behavior with older 0.5.x releases.
  Fix: Upgrade to the latest 0.5.x release to ensure correct merging and application of server extension configurations.

Install

• pip install voila Install Voila
• conda install -c conda-forge voila Install with Conda

Imports

• Voila

  from voila.app import Voila

  While Voila is primarily used via its command-line interface, `voila.app.Voila` is the main application class for programmatic embedding or testing.

Quickstart

Create a Jupyter notebook with interactive widgets and save it. Then, run Voila from the command line to serve it as a standalone web application. Access it in your web browser, typically at `http://localhost:8866`.

# Save this as `my_dashboard.ipynb`
import ipywidgets as widgets
from IPython.display import display

slider = widgets.IntSlider(min=0, max=100, step=1, description='Value:')
output = widgets.Output()

def on_value_change(change):
    with output:
        output.clear_output()
        print(f"Slider value is: {change['new']}")

slider.observe(on_value_change, names='value')

display(slider, output)

# Run from your terminal:
# voila my_dashboard.ipynb