使用可在浏览器中运行（无需本地依赖）、支持离线操作且可单文件共享的完整数据栈，创建交互式数据应用。

什么是 Preswald？

Preswald 是一个用于在 Python 中构建交互式数据应用的静态站点生成器。它将计算、数据访问和 UI 打包成自包含的数据应用，在浏览器本地运行。基于 Pyodide 和 DuckDB 的 WASM 运行时，Preswald 能够实现快速、响应式且可共享的便携式文件型应用。

你可以把 Preswald 看作是更重型 Web 应用平台的轻量级替代方案。它提供了内置的 UI 组件和响应式状态跟踪功能，因此你可以用它来构建仪表盘、报告、原型、工作流和笔记本，这些应用默认具有响应性、可移植性和安全性。

Preswald 尤其适用于以下场景：

• 当你希望将逻辑、UI 和数据打包成一个可共享的文件时
• 当你需要向利益相关者交付一个无需安装任何软件的工具时
• 当你处理敏感数据并需要完全的本地控制时
• 当你想为 AI 系统提供结构化且可修改的工具时

主要特性

• 基于代码。用 Python 编写应用，而不是在笔记本或 JS 框架中编写
• 文件优先。只需一条命令即可创建一个完整的 .html 应用
• 专为计算设计。直接在浏览器中使用 Pyodide + DuckDB
• 可组合的 UI。使用预构建的组件，如表格、图表、表单
• 响应式引擎。仅重新运行所需部分，由依赖关系的 DAG 驱动
• 本地执行。无需服务器。即使数据量大也能离线运行
• 适合 AI。应用可被智能体完全检查和修改

导出为静态应用

preswald export

此命令会将你的应用构建为 dist/ 目录下的静态站点。该文件夹包含运行你的应用或分享它所需的所有文件。

• 在任何现代浏览器中均可离线使用
• 打包了你的 Python 代码（通过 Pyodide）、数据和 DuckDB 查询
• 保留了应用的 UI、逻辑和响应式状态
• 可作为文件夹分享，也可嵌入到托管平台上

安装

https://pypi.org/project/preswald/

pip install preswald

或者

uv pip install preswald

快速入门

pip install preswald
preswald init my_app
cd my_app
preswald run

这将创建一个名为 my_app 的文件夹：

my_app/
├── hello.py           # 你的应用逻辑
├── preswald.toml      # 应用元数据和配置
├── secrets.toml       # 秘密信息（例如 API 密钥）
├── data/sample.csv    # 输入数据文件
├── images/logo.png    # 自定义品牌标识

编辑 hello.py 来构建你的应用。

from preswald import text, table, get_df

text("# Hello Preswald")
df = get_df("sample.csv")
table(df)
...

现在可以在本地运行你的应用：

preswald run

此命令会启动一个开发服务器，Preswald 会告知你应用的运行地址。通常如下所示：

🌐 应用正在运行：http://localhost:8501

打开浏览器，瞧——你的第一个 Preswald 应用就上线了！

配置

Preswald 使用一个简单的 preswald.toml 文件进行配置。该文件定义了应用的元数据、运行时设置、UI 品牌标识和数据源。以下是一个示例：

[project]
title = "Preswald 项目"
version = "0.1.0"
port = 8501
slug = "preswald-project"
entrypoint = "hello.py"

[branding]
name = "Preswald 项目"
logo = "images/logo.png"
favicon = "images/favicon.ico"
primaryColor = "#F89613"

[logging]
level = "INFO"  # 选项：DEBUG、INFO、WARNING、ERROR、CRITICAL
format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

应用场景

• 分析师仪表盘。构建数据摘要和可视化，以静态网站形式分享。示例 1 示例 2 示例 3
• 交互式报告。交付可根据用户输入实时更新的笔记本和报告。示例 1 示例 2 示例 3
• 数据检查工具。使用快速、专用的 UI 探索文件、日志或快照。示例 1 示例 2 示例 3
• 离线工具包。为野外工作或安全/气隙环境打包应用。示例 1 示例 2 示例 3
• 实验面板。比较运行结果、跟踪指标，并以独立的交互式应用展示成果。示例 1 示例 2 示例 3

📚 文档

我们随时为您提供帮助！请访问 Preswald Docs 查看完整文档。

🤝 贡献

请查看 CONTRIBUTING.md。

🎉 加入社区

• GitHub Issues：发现错误？请在此处告知我们 这里。
• 社区论坛：请在此处联系我们 这里。
• 讨论区：在我们的 讨论区 分享您的想法并提问。
• 贡献者：认识那些让 Preswald 更加出色的优秀人士 这里。

📢 保持联系

📄 许可证

Preswald 采用 Apache 2.0 许可证授权。

✨ 贡献者

感谢所有为 Preswald 做出贡献的伙伴 💜

Preswald 快速上手指南

Preswald 是一个用于构建交互式数据应用的 Python 静态站点生成器。它将计算逻辑、数据访问和 UI 组件打包成独立的单文件应用，直接在浏览器中运行（基于 WASM、Pyodide 和 DuckDB），无需本地服务器依赖，支持离线运行且易于分享。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Windows、macOS 或 Linux
• Python 版本：Python 3.7 或更高版本
• 包管理工具：pip 或 uv
• 浏览器：任意现代浏览器（Chrome, Edge, Firefox, Safari 等）

注意：Preswald 的核心优势在于“无本地依赖”。虽然开发时需要 Python 环境来初始化和运行开发服务器，但生成的最终应用是一个纯静态文件，用户无需安装任何环境即可在浏览器中打开。

安装步骤

您可以使用 pip 或 uv 进行安装。国内开发者若遇到下载速度慢的问题，建议配置国内镜像源。

方式一：使用 pip (推荐配置国内源)

# 使用阿里云镜像源安装
pip install preswald -i https://mirrors.aliyun.com/pypi/simple/

# 或使用清华镜像源
pip install preswald -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：使用 uv (速度更快)

uv pip install preswald

基本使用

只需三个命令即可创建并运行您的第一个 Preswald 应用。

1. 初始化项目

运行以下命令创建一个名为 my_app 的新项目文件夹：

preswald init my_app
cd my_app

初始化后，目录结构如下：

my_app/
├── hello.py           # 应用主逻辑代码
├── preswald.toml      # 应用配置与元数据
├── secrets.toml       # 敏感信息配置（如 API Key）
├── data/sample.csv    # 示例数据文件
└── images/logo.png    # 自定义品牌图片

2. 编写应用逻辑

编辑 hello.py 文件，使用 Preswald 提供的组件构建界面。以下是一个最简单的示例：

from preswald import text, table, get_df

# 添加标题
text("# Hello Preswald")

# 读取数据 (自动从 data/ 目录加载)
df = get_df("sample.csv")

# 渲染表格
table(df)

Preswald 内置了丰富的组件（如 chart, form, button 等），并支持响应式状态追踪，所有逻辑均使用标准 Python 编写。

3. 运行应用

在项目根目录下执行以下命令启动开发服务器：

preswald run

终端将输出类似以下信息：

🌐 App running at: http://localhost:8501

在浏览器中访问该地址，即可看到您创建的交互式数据应用。

4. 导出为独立应用 (可选)

完成开发后，您可以将应用打包为一个完全独立的静态站点，以便离线分享或部署：

preswald export

该命令会在 dist/ 目录下生成包含所有代码、数据和 UI 的静态文件。您可以直接将此文件夹发送给他人，或托管在任何静态网页服务上，用户无需安装 Python 即可在浏览器中直接使用。