Frequently asked questions

Try Safe Launch: touch and hold the Pythona icon on the Home Screen, then choose “Safe Launch”.

A crash at startup may be related to restoring previously opened files or folders. Safe Launch resets the saved open tabs and folder location, starting with an empty editor and the local Documents folder. Your script files are kept.

Once the app opens, try opening the folders and files you were using one at a time to see whether a particular file or location triggers the issue. If opening a file causes another crash and “Semantic Highlighting” is enabled, use Safe Launch again, turn off “Semantic Highlighting” under “Settings → Theme”, and retry.

App updates do not automatically replace saved example scripts. If an example stops working after an update, try restoring the examples included with your current app version and running it again.

Back up any examples you have edited first, then choose “Settings → Restore Example Scripts”. This overwrites example files with matching names in the examples folder.

Restoring examples does not reset installed Python packages. If a dependency version conflict remains, check the installed package versions listed in the error.

Repeated crashes while typing in the editor may be related to code completion. Turn off “Automatically Show Suggestions” under “Settings → Code Completion”, then try typing in the same file again to see whether it still crashes.

When reporting the issue, include the code snippet that triggers it, the exact typing steps, and whether the crash still occurs with “Automatically Show Suggestions” turned off.

Stop requests an interruption, but it cannot interrupt every operation immediately. Calls such as time.sleep(), waits for network responses or locks, and some native library computations must return before execution can stop. An import must also finish before stopping.

If it still won’t stop after waiting, save your files, then close Pythona from the iOS app switcher and reopen it.

If the issue keeps happening, send code and steps that reproduce it when reporting the problem.

While a script is running, choose “Send EOF” from the console input field’s edit menu, or press Ctrl+D on an external keyboard. Any text in the input field is sent first, then input ends for the current run.

Touch and hold the editor’s Run button, then select “Run With...”. Arguments are passed to the script as sys.argv[1:]. Use “Edit Run Configurations...” in the same menu to save frequently used arguments and set a default configuration.

Tap the filename at the top of the editor, select “Shortcuts”, and copy the “Script Path”. In the Shortcuts app, add Pythona’s “Run Python Script” action and enter the path. You can add arguments if needed and pass the action’s returned text output to subsequent actions.

Open the script in Pythona, tap the filename at the top of the editor, select “Shortcuts”, and copy the “URL”.

In the Shortcuts app, create a shortcut, add the “Open URLs” action, and paste the URL you copied.

Open the shortcut’s “Details”, choose “Add to Home Screen”, set the name and icon, and tap “Add”.

Tapping the Home Screen icon will then open Pythona and run the script.

The Package Manager installs third-party libraries distributed as pure-Python wheels. Some libraries are only available as source code or require compiled extensions written in C, C++, Rust, or similar languages, so they cannot be installed as they would on a computer. Native libraries such as NumPy and SciPy are precompiled and included with the app.

Pure-Python libraries must also be compatible with Python 3.14 and iOS. They may still fail to run if they depend on system features that are unavailable in this environment.

All projects share the device’s user package environment. Installation reuses existing dependencies that meet the requirements; otherwise, it may upgrade or downgrade user-installed pure Python dependencies. Packages bundled with the app are not automatically replaced.

Before changing a version, the installer checks relevant dependencies declared by other installed packages. It stops and explains the reason if it finds a conflict or a requirement it cannot handle. It does not try every version combination or detect every compatibility issue.

You can specify compatible versions, uninstall conflicting packages you no longer need and retry, or write Python scripts to download and deploy pure Python packages and manage their dependencies yourself. Calls to pythona.packages.install() still follow these rules; manual installation is also subject to Python and iOS compatibility limits. Restart Pythona after replacing a package you have already imported.

No. Libraries installed through the Package Manager are stored locally on the current device and shared by scripts in local storage, iCloud, and external folders.

After syncing a project through iCloud, install its dependencies separately on the other device.

Pythona includes cocoa-py, whose scene module supports games, animations, and interactive graphics. photos lets you select photos and videos through the system photo picker or save them to the photo library. audio provides playback, recording, and audio effects, while coreml loads Core ML models and runs inference on the device.

Use the pythona package to work with app features: pythona.packages installs third-party packages, and pythona.ai lets you create, read, and update custom AI provider configurations.

For additional iOS system features, we recommend rubicon-objc to call native iOS APIs from Python, including UIKit for native interfaces. See the device information and WKWebView examples in the app.

cocoa-py is open source and also supports macOS; available features vary by platform. Source code and API documentation are on GitHub. Issues and pull requests are welcome.

For 2D games, animations, and audio playback, we recommend pygame (the app includes pygame-ce). pygame.mixer can play music or sound effects on its own, without creating a window.

You can build interfaces or web games with HTML, CSS, and JavaScript, then display them in Pythona using WKWebView. Web content is easy to reuse across platforms. When moving to another platform, you’ll need to adapt the code that displays it in WKWebView and connects it to Python or iOS features.

For native iOS interfaces, use rubicon-objc to call UIKit. Code that uses UIKit still depends on iOS.

Pythona also supports Tkinter for running existing Tkinter scripts or building simple tools. Its interface has a traditional desktop look. If the look and feel on mobile devices is a priority, we recommend a web interface or UIKit through rubicon-objc. The app includes examples.

For code projects, we recommend Git: clone the same remote repository in Pythona and on your computer, commit and push your changes, then pull the updates on the other device.

You can also sync files through iCloud Drive or export them using the system share menu. When transferring files to or from a Mac, AirDrop is another option.

You can enable “File Server” in the app, then use a browser on a computer connected to the same local network to visit the address shown in the app and upload or download files. The server has no login password. Use it on a trusted network and stop it when you finish transferring files.

MLX: The app includes MLX, which you can use with mlx-lm to run compatible language models. See examples/llm_demo.py in the app; its first run installs dependencies online and downloads a model from Hugging Face. Your device must support MLX and have enough memory. Speed and the size of models you can run depend on device performance and memory.

Apple Foundation Models: Use the included apple-fm-sdk to access Apple’s on-device model, importing it in Python with import apple_fm_sdk. You need iOS / iPadOS 26 or later, a supported device with Apple Intelligence enabled, and the system model ready to use. Availability also depends on language and region. See the documentation below for API usage.

Both options run model inference on the device. Downloading dependencies and models requires internet access; scripts or assistant tools that use online services also make network requests.

Use the open-source Pythona AI Setup project to create AI assistant configurations for Apple Foundation Models or local MLX models.

Clone the project in Pythona and run main.py from the project root. Follow the page to choose a model and tools and add a configuration, then select that connection in the AI assistant settings. See the project README for detailed steps.

An MLX model must support tool calling to use assistant tools such as reading and writing files or running Python. Models without tool support can be used for conversation with all tools disabled.

The AI assistant uses the current conversation’s workspace as its default project directory. Before sending the first message in a new conversation, use “Change Workspace” to choose a folder. Navigating to another directory in the file browser does not change an existing conversation’s workspace.

The AI assistant can also call run_python to execute Python code and read files and folders within the app, including content outside the workspace. This access is not restricted to the selected workspace.

Yes. Create an AGENTS.md file at the root of the current conversation’s workspace to provide project information, coding conventions, and other collaboration guidelines.

The assistant automatically reads this file when processing each new message. After you save changes, they take effect the next time you send a message. Only AGENTS.md at the workspace root is loaded automatically; files with the same name in subdirectories are not automatically merged.

A custom provider lets you connect to AI services using your own JavaScript code. You can use APIs, authentication methods, or service features that built-in providers do not yet support, and add custom tools.

JavaScript lets the code for AI service connections, authentication, and response handling run in its own environment, so it doesn’t interfere with your Python environment.

Custom tools can call external services or wrap run_python so the assistant can run Python scripts and access iOS features through those scripts.

If the built-in providers already meet your needs, no extra configuration is necessary. If you need a custom provider, refer to the JavaScript API and examples on the configuration page.

No. You can use your purchased Pro access on other devices by signing in to the App Store with the same Apple Account you used for the purchase.

If you still see a trial notice or the purchase screen after installing Pythona on a new device or reinstalling it, your purchase status may not have synced yet. Connect to the internet and tap “Restore Purchases” on the purchase screen.

Restoring purchases is free. Even if you tap the purchase button again, you will not be charged again for the same Pro purchase you already own under the same Apple Account.

Your Pro purchase is linked to the Apple Account you used in the App Store when you bought it. If you switch to another account that has not purchased Pro, Pro may be unavailable. Switch back to the account you used for the purchase in the App Store, then tap “Restore Purchases” in Pythona.

If frequently switching App Store accounts affects your use of Pythona, please contact us.