haplollc/terrarium

Terrarium is a Swift package that embeds a real Python 3.13 interpreter inside iOS and macOS apps, so developers can run Python code directly on device without a server or a subprocess. It bundles CPython through a Python.xcframework, which means pure Python scripts run natively and fast, with no transpiling step involved. The standout feature is inline package installation. A script can start with a line like percent pip install requests, and Terrarium resolves that package from PyPI, downloads a wheel, and stores it in a writable folder so it survives the next app launch. For packages with C extensions that Apple platforms cannot easily support, such as matplotlib, numpy, pandas, scipy, and scikit-learn, Terrarium automatically switches to a hidden WKWebView running Pyodide, a version of CPython compiled to WebAssembly with roughly 250 prebuilt scientific packages available. The package includes a SwiftUI runner sheet with run, stop, and clear controls, plus proper cancellation support. It shows live byte level progress bars while packages download, supports colored terminal output through libraries like rich and colorama, and automatically displays matplotlib charts in a view tab without needing plt.show(). Network requests work out of the box through the requests library, using Python's built in SSL support for HTTPS. There is also a package manager interface where a user can search installed packages, see their storage size, and delete them individually. A developer can force which runtime handles a script with a magic comment, choosing either the native CPython path or the Pyodide WASM path, and can list installed packages with a pip style command showing whether each one is bundled, user installed, or running through Pyodide. Installing from a requirements.txt file is also supported using the standard pip flag. The whole thing ships as a self contained SwiftPM package, with all its resources bundled so there is no manual Xcode folder setup required. In short, it gives an iOS or macOS app the ability to run and extend real Python code, including much of the scientific Python stack, entirely on the user's device.