repository·main·Indexed 41 days ago
https://github.com/ohtaman/streamlit-desktop-appA library to convert web-based Streamlit applications into standalone, native desktop applications using PyInstaller and PyWebview. It provides a CLI for building executables and a Python API via the start_desktop_app function to launch apps in a native window. Version 0.0.0.
You can install the library using either pip or Poetry.
Poetry Users: Due to PyInstaller limitations, ensure your pyproject.toml specifies a compatible Python version range: python = "^3.10,<3.13".
# Using pip
pip install streamlit-desktop-app
# Using Poetry
poetry add streamlit-desktop-appYou can pass additional flags to the build command using --pyinstaller-options and --streamlit-options.
PyInstaller Options: Use --pyinstaller-options followed by standard PyInstaller flags (e.g., --onefile, --noconfirm).
Streamlit Options: Use --streamlit-options followed by Streamlit configuration flags (e.g., --theme.base=dark).
# Example with both PyInstaller and Streamlit options
streamlit-desktop-app build example.py --name MyStreamlitApp --icon path/to/icon.ico --pyinstaller-options --onefile --noconfirm --streamlit-options --theme.base=darkTo confirm the installation was successful, run the module directly. This will launch a pre-built Streamlit app in a desktop window to demonstrate the library's capabilities.
python -m streamlit-desktop-appUse the streamlit-desktop-app build command to convert your Python script into a standalone executable. The resulting file will be placed in the dist/ directory.
streamlit-desktop-app build example.py --name MyStreamlitAppYou can launch the included example application using either the Python module interface or the installed console script.
As a Python module: Use this if you are running from the source directory or have the package installed in your environment.
Via console script: Use this after installing the package via pip. Note that the command expects a script path to run.
# Run the default example module
python -m streamlit_desktop_app
# Run a specific script using the installed CLI
streamlit-desktop-app run example.pypython -m streamlit_desktop_appTo run desktop applications on Windows, the following components must be installed for pywebview compatibility:
dotnet --info.Use the start_desktop_app function to launch your app within a desktop window from within a Python script. This is useful for embedding logic before the app starts or for development/testing.
from streamlit_desktop_app import start_desktop_app
start_desktop_app("example.py", title="My Streamlit Desktop App")If you require full control over the build process, you can bypass the CLI wrapper and run PyInstaller directly. You must include specific flags to ensure Streamlit's assets and metadata are correctly packaged.
pyinstaller --collect-all streamlit --copy-metadata streamlit --name "MyStreamlitApp" --onefile --windowed --splash path/to/splash_image.png -i path/to/icon.ico example.pyThe start_desktop_app function is the primary entry point for launching a Streamlit script as a standalone desktop application. It takes the path to a Python script and allows you to configure basic window properties like the application title.
Parameters:
script_path (str): The filesystem path to the .py file containing your Streamlit application.title (str, optional): The title of the desktop application window.from streamlit_desktop_app.core import start_desktop_app
start_desktop_app("path/to/your_app.py", title="My Streamlit Desktop App")The start_desktop_app function is the primary entry point for launching a Streamlit script within a pywebview desktop window. It manages the entire lifecycle: finding a free port, launching the Streamlit server in a background process, waiting for the server to become responsive, and opening the desktop window. When the window is closed, it ensures the Streamlit process is terminated.
Note on Configuration: The following Streamlit options are automatically overridden by the application to ensure proper desktop behavior and will be ignored if provided in the options dictionary:
server.address (set to localhost)server.port (set to a dynamically found free port)server.headless (set to true)global.developmentMode (set to false)from streamlit_desktop_app import start_desktop_app
# Basic usage
start_desktop_app('app.py')
# Custom window size and title
start_desktop_app(
'app.py',
title='My Streamlit App',
width=1200,
height=800
)
# With additional Streamlit options (excluding overridden ones)
start_desktop_app(
'app.py',
options={
'theme.primaryColor': '#F63366',
'theme.backgroundColor': '#FFFFFF'
}
)The build_executable function is the primary entry point for packaging a Streamlit application into a standalone executable using PyInstaller. It automates dependency analysis (via AST), creates a necessary wrapper script, and configures PyInstaller to include Streamlit and your application script.
Arguments:
script_path (str): Path to your Streamlit Python file.name (str): The desired name for the output executable.icon (str, optional): Path to an .ico file for the executable icon.pyinstaller_options (List[str], optional): Additional command-line flags to pass directly to PyInstaller (e.g., ['--onefile', '--clean']).streamlit_options (List[str], optional): Streamlit configuration flags (e.g., ['--theme.base', 'dark']) to be applied when the app launches.from streamlit_desktop_app.build import build_executable
# Basic usage
build_executable(
script_path='app.py',
name='MyApp',
icon='icon.ico'
)
# With additional options
build_executable(
script_path='app.py',
name='MyApp',
icon='icon.ico',
pyinstaller_options=['--onefile', '--clean'],
streamlit_options=['--theme.primaryColor', '#F63366']
)The extract_imports function uses Abstract Syntax Tree (AST) analysis to identify all import and from ... import ... statements in a given Python file. This is used by the build process to automatically identify and include --hidden-import dependencies for PyInstaller.
from streamlit_desktop_app.build import extract_imports
# Returns a sorted list of unique, fully qualified module names
imports = extract_imports('app.py')