pack.pack

pack.pack(
    app_file,
    extra_files_to_embed=None,
    extra_files_to_link=None,
    prepend_github_path=None,
    github_branch='main',
    requirements=None,
    title='App',
    output_dir='docs',
    output_file='index.html',
    stylesheet_version='0.80.5',
    js_bundle_version='0.80.5',
    use_raw_api=True,
    pyodide_version='default',
    replace_df_with_table=False,
    force_redownload_material_icons=False,
    print_preview_message=True,
    run_preview_server=False,
    randomise_preview_port=True,
    port=8000,
    automated_stlite_fixes=True,
)

Pack a Streamlit app into a stlite-compatible index.html file.

This function reads a Streamlit Python script, injects it into an HTML template compatible with stlite, and writes the output as index.html. The resulting HTML can be served as static content (e.g., via GitHub Pages).

If additional pages are found in a ‘pages’ folder at the same level as the main app file, these will be added in as additional files.

Note that the package will access the internet to download the latest version of Google’s material UI font. This is necessary to ensure all standard streamlit icons display correctly, as well as allowing the use of material icons elsewhere in the app where streamlit supports this.

Parameters

Name	Type	Description	Default
app_file	str	Path to the main Streamlit application file (entrypoint) (e.g., "app.py"). If additional pages are found in a ‘pages’ folder at the same level as this main app file, these will be added in as additional files.	required
extra_files_to_embed	list[str]	Additional files to mount directly into the app (e.g. .streamlit/config.toml). This will work best with files that are primarily text-based (e.g. .py, .toml, .csv). If binary files (e.g. .png, .jpg, .mp4) are provided, the script will attempt to convert them to base64 encoded representations that can live entirely within your file. However, this can massively increase the size of your resulting index.html file, and is currently experimental. For binary files it is recommended that you pass them using the ‘extra_files_to_link’ option instead.	None
extra_files_to_link	list[str] or dict	Additional files to hyperlink to. - If passed as a list, must be used with the argument ‘prepend_github_path’. The list must be a list of relative filepaths. - If passed as a dict, expects key:value pairs of relative_filepath: url e.g. {‘img/my_img.png’: ’https://raw.githubusercontent.com/your-github-username/your-github-repository/refs/heads/main/img/my_img.png} Can only be used with the raw API (use_raw_api=True). Defaults to None	None
prepend_github_path	str	If files to be linked are stored on github, you can pass them as relative paths in the ‘extra_files_to_link’ argument, and then use this argument to automatically generate the url links to the files in your repository. Needs to passed in the format “username/reponame” e.g. a username of Bergam0t with a reponame of my-streamlit-app would be “Bergam0t/my-streamlit-app” Then, for example, if you passed a list of [‘img/my_img.png’] to the ‘extra_files_to_link’ argument, it would automatically generate the url of https://raw.githubusercontent.com/Bergam0t/my-streamlit-app/refs/heads/main/img/my_img.png Ignored if ‘extra_files_to_link’ is None. Can only be used with the raw API (use_raw_api=True). Defaults to None	None
github_branch	str	If files to be linked to on Github need to come from a branch other than main, provide the name of the desired branch here. e.g. a username of Bergam0t with a reponame of my-streamlit-app would be “Bergam0t/my-streamlit-app” If you passed ‘dev’ as your branch to this argument, and then passed a list of [‘img/my_img.png’] to the ‘extra_files_to_link’ argument, it would automatically generate the url of https://raw.githubusercontent.com/Bergam0t/my-streamlit-app/refs/heads/dev/img/my_img.png Ignored if ‘extra_files_to_link’ is None or prepend_github_path is None. Can only be used with the raw API (use_raw_api=True). Defaults to ‘main’	'main'
requirements	str or list of str	Either: - Path to a requirements.txt file (str), or - A list of required Python packages (list of str).	None
title	str	Title to insert into the HTML <title> tag. Default is "stlite app".	'App'
output_dir	str	Directory where the generated index.html will be written. Default is "docs".	'docs'
use_raw_api	bool	If True, will use the version of the template that calls the mount() API explicitly. Default is True.	True
pyodide_version	str	If not ‘default’, tries to serve the requested pyodide version from the pyodide CDN. Only works with raw API. Versions can be found here: https://pyodide.org/en/stable/project/changelog.html Default is ‘default’ (use default pyodide version, which is linked to stlite version)	'default'
replace_df_with_table	bool	Some versions of streamlit and stlite seem to have issues with displaying tables that should be shown with st.dataframe. This option will replace all instances of st.dataframe with st.table, removing interactivity from the tables but ensuring they do at least display. Default is False.	False
print_preview_message	bool	If True, prints a message explaining how to start a preview server. Ignored if run_preview_server is True. Default is True.	True
run_preview_server	bool	If True, starts a small server previewing the output file. Supersedes print_preview_message. If both are True, only the preview server will be started. Default is True.	False
randomise_preview_port	bool	If True, this will choose a different port from 8000-8999 each time. This can prevent clashes - for example, if you pack two apps and accidentally leave one running… Ignored if run_preview_server is False Default is True	True
port	int	If randomise_preview_port is False, will use the port provided here. Ignored if run_preview_server is False Default is 8000	8000
automated_stlite_fixes	bool	If True, applies some automated fixes for common stlite issues - Inserts an await statement at the start of any st.spinner blocks to ensure the code in the spinner is non-blocking and also that the spinner itself is displayed - [PLANNED] Replace time.sleep with async equivalent	True

Raises

Name	Type	Description
	FileNotFoundError	If the specified app_file does not exist.
	ValueError	If requirements is not a list or a valid requirements file path.

Notes

• Currently supports only single-page Streamlit apps.
• Future versions will support multi-page apps, additional resources, and GitHub Pages deployment automation.

Examples

Pack an app using a requirements file:

>>> from stlitepack import pack
>>> pack("app.py", requirements="requirements.txt", title="My App")

Pack an app with inline requirements:

>>> pack("app.py", requirements=["pandas", "numpy"], title="Data Explorer")

The resulting HTML file will be written to dist/index.html by default.