Pythonista 中安装第三方纯 Python 库的方法与限制

在 iOS 平台运行的 Pythonista 提供了完整的 Python 解释器与专用脚本环境，但由于苹果操作系统的沙盒保护机制以及对动态可执行代码签署的严格限制，在 Pythonista 中扩展第三方库与桌面环境有本质区别。要在 Pythonista 中安装第三方库，核心答案是：仅支持不包含任何 C/C++、Rust 等编译型底层代码的“纯 Python 库（Pure Python Packages）”，通常可通过内置或第三方终端工具 StaSh 的 pip 命令快速下载，或直接将模块源码目录手动放置到特定的 site-packages 路径下实现导入。

一、Pythonista 的模块搜索路径与运行环境

理解 Pythonista 如何加载模块，是完成安装的第一步。在标准桌面系统中，pip 会将文件写入系统级或用户级环境的 site-packages 目录中。而在 Pythonista 的 iOS 应用沙盒中，文件系统被严格划分为只读的应用束（App Bundle）目录与用户可读写的文稿（Documents）目录。

Pythonista 解释器在初始化时，会自动将以下几个关键路径注入到 sys.path 中：

• 只读标准库与内置扩展区：位于应用本体内部，预装了 Python 核心标准库以及开发者预编译的部分二进制扩展（如旧版 NumPy、Matplotlib、SymPy 及 iOS 特有的 ui、scene、photos 模块）。该目录无法写入任何新文件。
• 全局用户库目录（~/Documents/site-packages-3 或 site-packages）：位于用户文稿目录下，可读可写。放置在此处的 .py 文件或包目录对于所有脚本均全局可见。
• 脚本所在当前工作目录：执行脚本所在的同一文件夹，优先级通常高于全局包路径。

只要确认待安装的库是纯 Python 实现，将其放置在 site-packages-3（对于 Python 3 环境）或当前脚本文件夹下，解释器就能正常通过 import 引用。

二、方法一：使用 StaSh 终端的 pip 命令安装

StaSh（Pythonista Shell）是社区为 Pythonista 打造的类 Unix 终端运行环境，完全使用纯 Python 编写。它内置了定制版的 pip 工具，能够解析 PyPI 索引、下载依赖包并解压部署到 site-packages-3 目录，是目前最常用、最高效的安装途径。

1. 安装并初始化 StaSh

在 Pythonista 默认安装下并没有终端界面。需要先新建一个临时脚本执行官方引导程序。新建名为 install_stash.py 的文件，粘贴如下代码并运行：

import urllib.request
exec(urllib.request.urlopen('https://raw.githubusercontent.com/ywangd/stash/master/getstash.py').read())

脚本执行完成后，Pythonista 会自动在根目录（即 This iPhone 或 This iPad 页面）下生成一个名为 launch_stash.py 的文件。此时必须彻底退出 Pythonista 应用并重新启动，以确保模块加载缓存被清空。

2. 打开终端并运行 pip 命令

重启后打开 launch_stash.py 并点击运行，屏幕下方会弹出全屏控制台，显示类似 [~/Documents]$ 的命令行提示符。此时可以直接使用 pip：

# 搜索并安装指定的纯 Python 库（以 requests 为例，注：Pythonista 已预装部分旧版本，此处演示常规命令）
[~/Documents]$ pip install tabulate

# 指定安装纯 Python 轮子包或确定版本的库
[~/Documents]$ pip install markdown==3.4.1

# 查看当前已安装的包列表
[~/Documents]$ pip list

三、方法二：手动解压与文件放置法

当网络受限、PyPI 索引在 StaSh 中解析报错，或者需要安装来自 GitHub 仓库的单文件模块时，直接手动部署是成功率最高的方式。

1. 寻找或下载纯 Python 资源

在 PyPI 网页（pypi.org）中搜索目标库，转到“Download files”页面。在可用分发文件中，优先下载满足以下命名的轮子文件（Wheel）或源码压缩包（tar.gz/zip）：

• <包名>-<版本>-py2.py3-none-any.whl 或 *-py3-none-any.whl（这表明该包是无架构依赖的纯 Python 代码）。
• 无 C 扩展源码的 .tar.gz 源码包。

2. 解压与目录结构要求

.whl 文件本质上就是标准的 .zip 压缩包。可以在电脑或 iOS 上的解压应用将其后缀改为 .zip 并解压。解压后通常会包含两类目录：

1. 库核心代码目录：例如 requests（包含 __init__.py 的文件夹），或者单文件模块如 bottle.py。
2. 元数据目录：以 .dist-info 结尾的文件夹（如 requests-2.31.0.dist-info）。

将核心代码目录拷贝至 Pythonista 的 ~/Documents/site-packages-3/ 下即可（元数据目录仅供 pip 记录版本，不影响解释器直接 import）。

3. 利用 iOS“文件”应用与隔空投送（AirDrop）

在 iOS 系统的“文件”App 中，Pythonista 具有专属的应用存储空间：

• 打开 iOS 自带的“文件”App，在“浏览”标签页中进入“我的 iPhone”或“我的 iPad”；
• 找到名为 Pythonista 的目录，进入 site-packages-3；
• 直接将 Mac/PC 上解压好的纯 Python 文件夹通过 AirDrop 传入并移动至该目录下。

四、方法三：通过轻量 Python 脚本实现自动化抓取与解压

如果在 iOS 设备上不方便操作多层文件管理器，可以直接在 Pythonista 中编写一个 10 行左右的小脚本，通过 urllib 直接抓取 GitHub 或 PyPI 上的纯 Python 文件并存入 site-packages-3。

import os
import sys
import urllib.request
import zipfile
import io

def install_pure_zip(zip_url, target_folder_name):
    site_packages = os.path.expanduser('~/Documents/site-packages-3')
    os.makedirs(site_packages, exist_ok=True)
    
    print(f"正在下载: {zip_url}")
    req = urllib.request.Request(zip_url, headers={'User-Agent': 'Mozilla/5.0'})
    with urllib.request.urlopen(req) as resp:
        zip_data = resp.read()
    
    print("下载完成，正在解压...")
    with zipfile.ZipFile(io.BytesIO(zip_data)) as z:
        z.extractall(site_packages)
    print(f"解压完成，已部署至: {site_packages}")

# 示例：直接下载一个纯 Python 项目源码包
# install_pure_zip('https://github.com/user/pure-repo/archive/refs/heads/master.zip', 'pure-repo')

五、Pythonista 安装第三方库的技术限制

虽然通过上述方法可以扩展很多实用工具，但用户在尝试安装大型科学计算或加密库时，往往会遭遇 No module named ... 或找不到 .so 共享库的错误。这是由 iOS 底层安全架构与 Pythonista 的实现原理决定的硬性边界。

1. 缺乏本地编译工具链与 W^X 内存安全策略

在 Linux 或 macOS 上，使用 pip install 安装含有 C 代码的库时，系统会在后台唤起 gcc 或 clang 实时编译为 .so 动态链接库。iOS 系统本身没有提供用户态的 C/C++ 编译器，也不允许在应用沙盒内执行编译命令。

更关键的是，iOS 强制启用了内存 W^X（Write XOR Execute，即不可同时具有写与执行权限）机制，并且沙盒安全策略严格禁止使用 dlopen() 加载没有经过苹果官方签名、存放在 App Bundle 外的任意第三方动态库（如 .dylib 或 .so）。因此，即便用户在 Mac 上交叉编译出适用于 iOS 架构（arm64）的 .so 文件，直接拷贝到 Pythonista 的 site-packages 后尝试加载，也会被操作系统直接拦截或导致应用崩溃。

2. 常见热门库的兼容性归类

了解限制后，可以明确判断哪些库能够安装，哪些库必须放弃或寻找替代方案：

六、安装后的验证与故障排查清单

完成库的部署后，切勿直接在复杂工程中调用，建议新建一个简单的测试脚本，按以下流程进行核验与排查：

核心排查步骤与诊断代码

在 Pythonista 交互控制台（Interactive Prompt）中逐行执行以下检查：

# 1. 检查目标模块是否成功加载及其物理位置
import my_package
print(my_package.__file__)
# 正常应输出: /private/var/mobile/Containers/Data/Application/.../Documents/site-packages-3/my_package/...

# 2. 如果报 ModuleNotFoundError，检查 sys.path 是否包含 site-packages 路径
import sys
for p in sys.path:
    print(p)

# 3. 若路径缺失，可在脚本头部显式补齐（应急手段）
import os
import sys
site_pkg = os.path.expanduser('~/Documents/site-packages-3')
if site_pkg not in sys.path:
    sys.path.insert(0, site_pkg)

通过掌握上述路径结构、StaSh 命令行机制以及手动部署方法，并明确区分纯 Python 与 C 扩展的界限，即可在 Pythonista 中高效构建功能丰富的自动化脚本与工具链。