User Interface Configuration¶
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.
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
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
If you have such a configuration file, then the value associated with a
configuration parameter will override the one provided in the
method of your
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:
- port (int, default: 5000): the port that the server uses.
This parameter can be overridden using the -P or --port option when launching your application:
- 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.
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
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
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
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.
- 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
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.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
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
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
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¶
Gui instance runs, it creates a web server that serves the
registered pages, with the root of the site located where the
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
If a user requests a file whose path matches one that appears in
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
pyngrokpackage in your Python environment: When installing Taipy GUI:or independently:
pip install taipy-gui[pyngrok]
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
... 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
Your Flask server, running locally, will accept and serve connections from all around the world.