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 an .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 with option but when they can, the option is describe in the specific configuration parameter entry below.
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:
- title (str or None, default: "Taipy App"): the string displayed in the browser page title bar when navigating your Taipy application.
- favicon (str or None, default is the Avaiga logo): the path to an image file used as the page's icon when navigating your Taipy application.
- dark_mode (bool, default: True): whether the application shows in Dark mode (True) or Light mode (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 Notifications for details).
- debug (bool, default: True): set 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 warning from the websocket 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.
- flask_log (bool, default: False): if set to True, you can get a full, real-time log from the Flask server. This may be useful when trying the find the reason why a request does not behave as expected.
- use_reloader (bool, default: True): 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 the reloading only takes place if either the async_mode parameter of
Gui.run()is set to "threading" or the debug parameter is set to True.
- 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.
- propagate (bool, default: True): the default value that will be 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
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.
- theme (Union[dict[str, any], 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.
- 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.
- 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.
- data_url_max_size (int or None): the size below which the upload of file content is
performed as inline data. If a file content exceeds that size, it will actually create
a physical file on the server for your application to use. This upload mechanism is
used by the
The default is 50 kB.
- 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.
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 in situations where you already have a Web app running, and you 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.
Accessing your app from the Web¶
Ngrok provides a way to expose your local application to the public Internet. That 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 that
allows users to connect to it. This has the form
Your Flask server, running locally, will accept and serve connections from all around the world.