Skip to content

Configuring the GUI application

Applications created using the taipy.gui package can be configured for different use cases or environments.

This section describes how to configure an application and explains different deployment scenarios.

Configuring the Gui instance

The Gui instance of your application has many parameters that you can modify to accommodate your environment (such as development or deployment context) or tune the user experience.

Configuration parameters can be specified in the call to the run() method of your Gui instance using the kwargs parameter.

Configuring with a .env file

All parameters can also be set to any values and stored as a list of key-value pairs in a text file for your Gui instance to consume. The name of this file is the one provided as the env_filename parameter to the Gui constructor.

If you have such a configuration file, then the value associated with a configuration parameter will override the one provided in the run() method of your Gui instance.

Script options

The Python script that you launch to run your application can be provided with command-line options that Taipy can use to ultimately override configuration settings. Not all configuration parameters can be overridden by a command-line option, but when they can, the option is described below in the specific configuration parameter entry.

To see a list of all predefined Taipy options, you can run any Taipy script that runs a Gui instance with the -h option.

Here is the list of the configuration parameters you can use in Gui.run() or as an environment setting:

  • host (str, default: 127.0.0.1): the hostname of the server.
    This parameter can be overridden using the -H or --host option when launching your application:
    -H,--host <hostname>
  • port (int or "auto", default: 5000): the port that the server will use.
    When set to "auto", the server will attempt to run on a free port by checking the range of port numbers defined in the port_auto_ranges configuration parameter.
    This parameter can be overridden using the -P or --port option when launching the application:
    -P,--port <port>
  • debug (bool, default: False): set this parameter to True if you want to be provided with detailed debugging information messages from the server.
    If the debug mode is set, then the async_mode parameter of the call to Gui.run() is overridden to "threading" to use the Flask built-in development server.
    To avoid warnings from the web socket layer when using the debug mode, make sure you install the simple-websocket optional package.
    If debug is set to True, exceptions in user code will show the stack trace in the application's console.
    You can force the debug mode using the --debug option when launching your application.
    Or you can force not to use the debug mode using the --no_debug option when launching your application.
    To avoid warning messages from Flask, setting this parameter to True forces the value of the allow_unsafe_werkzeug parameter to True.
  • title (str or None, default: "Taipy App"): the string displayed in the browser page title bar when navigating your Taipy application.
  • dark_mode (bool, default: True): whether the application shows in Dark mode (True) or Light mode (False).
  • favicon (str or None, default is the Taipy logo): the path to an image file used as the page's icon when navigating your Taipy application.
  • run_browser (bool, default: True): when Gui.run() is invoked, Taipy GUI automatically runs the system's browser and opens a new page to display the application interface, unless this parameter is set to False.
  • margin (str or None, default: "1em"): a CSS dimension value that indicates how far from the border of the windows should your interface be. The default value avoids elements getting glued to the window borders, improving appearance.
  • system_notification (bool, default: True): if True, notifications will be sent by the system as well as the browser, should the system_notification parameter in the call to (notify()) be set to None. If False, the default behavior is to not use system notifications.
    See the section on Notifications for details.
  • notification_duration (int, default: 3000): the time, in milliseconds, that notifications should remain visible.
    See the section on Notifications for details.
  • watermark (str, default: "Taipy inside"): a faint text appearing on top of all application pages.
  • stylekit (Union[bool, dict[str, int, float], None]): If True or unspecified, use the default Stylekit for this application.
    If False, do not use the Stylekit.
    If this parameter is set to a dictionary, the keys are used as Stylekit variable names, whose values are overloaded by the value indicated in the dictionary.
  • theme (dict[str, any] or None): A dictionary that lets you customize the theme of your application.
    See the Themes section for details.
  • light_theme (Union[dict[str, any], None]): Similar to the theme setting, but applies to the light theme only.
  • dark_theme (Union[dict[str, any], None]): Similar to the theme setting, but applies to the dark theme only.
  • data_url_max_size (int or None): the size in bytes below which the upload of file content is performed as inline data. If a file content exceeds that size, it will create a physical file on the server so the application can read it. This upload mechanism is used by the file_download and the image controls.
    The default value is 50 kB.
  • use_reloader (bool, default: False): If True, the application watches its Python source file while running and reloads the entire script should the file be modified. If False, there is no such watch in place.
    You can force the use_reloader mode using the --use-reloader command line when launching your application.
    Or you can force not to use the use_reloader mode using the --no-reloader command line option when launching your application.
    Note that setting this to True forces the debug parameter to True, and the async_mode parameter to "threading".
    This setting is irrelevant in the context of Notebooks.
  • ngrok_token (str, default: ""): an authtoken, if you need to use Ngrok to expose your application to the Internet. See the section on Accessing your app from the Web for details.
  • change_delay (int, default: None): the delay, in milliseconds, used by some controls (namely slider, input, and number) before the user actions are sent to the backend server for further processing. This can be used when there is a significant network latency: user actions would then get stacked up on the front-end before the back-end had a chance to receive them, resulting in a poor user experience. This value should be less than 300 to ensure a smooth interaction with the control.
    The default value of None indicates that Taipy GUI does not use any delay.
  • propagate (bool, default: True): the default value that is used for every propagate property value, for all controls. Please look at the section on the propagate property for details.
  • time_zone (str, default: "client"): indicates how date and time values should be interpreted.
    You can use a TZ database name (as listed in Time zones list on Wikipedia) or one of the following values:
    • "client" indicates that the time zone to be used is the web client's.
    • "server" indicates that the time zone to be used is the web server's.
  • upload_folder (str or None, default: None): the local path where files are uploaded when using the file_selector control.
    The default value is the temp directory on the system where the application runs.
  • webapp_path (str, None): when working with the Taipy GUI source code, it may be helpful to indicate where to find the "webapp" directory that holds the client side of the package. You can use this setting to indicate where on your filesystem this directory should be searched.
    The default uses the path to the "webapp" directory within the installed Taipy GUI package.
  • chart_dark_template (dict[str, any] or None, default: None): a template for styling charts in dark mode. The full documentation for this object can be found in the documentation section for Plotly's layout template.
  • extended_status (bool, default: False): if set to True, the status page output is augmented with additional information.
  • flask_log (bool, default: False): if set to True, you can get a complete, real-time log from the Flask server. This may be useful when trying to find out why a request does not behave as expected.
  • notebook_proxy (bool, default: True): this setting only matters when running Taipy GUI in the context of Notebooks. If set to True, which is the default, the exposed port number (the one set in the port parameter) is just a proxy port to a dynamically generated port so that the user can stop and restart the server without depending on how quickly the kernel can clean up its resources.
    See the section on running Taipy GUI in Notebooks for more details.
  • single_client (bool, default: False): set to True if only a single client can connect. False, which is the default value, indicates that multiple clients can connect to the server.
    Note that this setting is forced to True when running in a Notebook context.
  • port_auto_ranges (list[tuple[int,int]]), default: [(49152, 65535)]: defines the ranges of port numbers to be used when the port configuration parameter is set to "auto".
    This parameter must be a list of tuples, each containing two integers that specify the start and end of a port range.
  • async_mode (str or None, default: "gevent"): specifies the deployment strategy for SocketIO, that Taipy GUI depends on.
    This parameter is forced to "threading" if debug or use_reloader is set to True.
  • server_config (dict[str, any], default: None): allows for fine-tuning the configuration of the underlying web server. The keys and types of values that you can set in this dictionary are the following:
    • flask (dict[str, any]): lets you specify the parameters to the Flask application object, as explained in the Flask Server Configuration documentation page. Each key/value pair is used when calling the Flask constructor.
    • cors (Union[bool, dict[str, any]]): if True, this indicates that you are using Flask CORS.
      If this entry holds a dictionary, then the key/value pairs of the dictionary are used to configure Flask CORS. All the details can be found in the Flask CORS Configuration documentation section.
    • socketio: (dict[str, any]): lets you specify the parameters to the Flask-SocketIO server that Taipy GUI creates. You can find all the documentation for all relevant key/value pairs in the Flask-SocketIO configuration documentation page.
    • *ssl_context" (str|tuple[str, str]): the value set when running the underlying SocketIO instance for SSL support.
      This will work for a Flask development server, for testing purposes but not when using "eventlet" or "gevent" async_mode. You will need to rely on your web server's documentation to learn how to enable SSL support and configure the server with a real TLS certificate.
  • run_in_thread (bool, default: False): if set to True, the underlying web server runs in a separate thread. In a Notebook context, this parameter is forced to True.
  • run_server (bool, default: True): must be set to False if you if you want to run this GUI application on an external server. Then Taipy GUI will not create or run the server, and it is up to the programmer to use the Flask instance returned by Gui.run() or Gui.get_flask_app() so it is served by the target web server.
  • base_url (str or None, default: "/"): a string used as a prefix to the path part of the exposed URL, so one can deploy a Taipy GUI application in a path different from the root of the web site.
  • allow_unsafe_werkzeug (bool, default: False): hides some Flask-SocketIO runtime errors in some debugging scenarios. This is set to True when debug is set to True.
  • use_arrow (bool, default: False): indicates whether or not to use the Apache Arrow technology to serialize data to Taipy clients. This allows for better performance in some situations.

Multiple Taipy services

To run the Taipy GUI service with some other Taipy services, please refer to the Running Taipy services section.

Using an external web server

Taipy user interfaces can be served by external servers. This happens when you already have a web application running and want to add the GUI capabilities of Taipy to it.

What you need to do in this case is use the flask parameter of the Gui constructor, setting it to the instance of the Flask server you are using.

Here is a short code sample that should make this straightforward:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from flask import Flask
from taipy import Gui

flask_app = Flask(__name__)

@flask_app.route("/home")
def home_page():
    return "The home page."

gui = Gui(page="# Taipy application", flask=flask_app)
gui.run()

The Flask server is created in line 4. Routes and such would be declared as usual (like in lines 6 to 8).

Note how we use the Flask instance to use it in the Gui constructor in line 10.

When gui is run (in line 11), Taipy will not create a server of its own. Instead, it will serve your GUI pages using the flask_app server created in line 4.

Protect your application files

When the Gui instance runs, it creates a web server that serves the registered pages, with the root of the site located where the __main__ Python module file is located.
This allows malicious users to potentially access the files of your application if those users know their path names: the main file of a Python application is often called main.py, so anyone could request the http://<url:port>/main.py and see your Python source code.
This can be even more dangerous if your application relies on data files that are meant to remain private. If a user of your application happens to discover the path to this file, the application has a security vulnerability because this file can be directly accessed using the underlying Web server.

The way to solve that issue is to configure the application server to indicate which requests are safe and which should be blocked.

Taipy GUI, however, comes with a simple feature that makes this configuration far simpler: Located next to the main module of your application, you can create a file called .taipyignore that lists files or directories that you want to protect against a direct request.
The syntax of this text file is identical to the syntax used by Git for its .gitignore file.

If a user requests a file whose path matches one that appears in .taipyignore then the Taipy web server returns an HTTP error 404 (Not Found), protecting your file from being downloaded without your consent.

Accessing your app from the Web

Ngrok provides a way to expose your local application to the public Internet. This allows anyone to access your application before deploying it in your production environment.

If you want to expose your application using Ngrok, you can follow these steps:

  • Install the pyngrok package in your Python environment: When installing Taipy GUI: 
    pip install taipy-gui[pyngrok]
    or independently: 
    pip install pyngrok
  • Create an account on the Ngrok web site.

  • That will drive you to a page where you can install the ngrok executable on your machine. Behind the scene, Ngrok will also send you a confirmation email providing a link that you must click to validate your registration and connect to your new account.
    Connecting to your account will provide you the Ngrok authtoken.

  • Add the NGrok authtoken to the call to run(): 

    ...
gui=Gui(...)
...
gui.run(ngrok_token="<ngrok_authtoken>")
...

  • When you run your Taipy script, the console will print out the public URL, allowing users to connect to it. This has the form http://<id>.ngrok.io.
    Your Flask server, running locally, will accept and serve connections from all around the world.