FAQ
よくある質問
起動と復元、コードの編集と実行、ライブラリと拡張機能、ファイル転送、AI モデルとアシスタント、購入と復元について。
起動と復元
Pythona を開くとすぐにクラッシュする場合は？
セーフ起動を試してください。ホーム画面で Pythona のアイコンを長押しし、「セーフ起動」を選びます。
起動時のクラッシュは、前回開いていたファイルやフォルダの復元に関連している可能性があります。セーフ起動は、開いていたタブやフォルダの記録をリセットし、空のエディタとローカルの Documents フォルダから開始します。スクリプトファイルは保持されます。
起動できたら、前回使用していたフォルダやファイルを一つずつ開き、特定のファイルや場所で問題が起きるか確認してください。ファイルを開くと再びクラッシュし、「セマンティックハイライト」が有効になっている場合は、もう一度セーフ起動を行い、「設定 → テーマ」で「セマンティックハイライト」をオフにしてから再試行してください。
アプリの更新後にサンプルスクリプトが動かなくなったら？
アプリを更新しても、保存済みのサンプルスクリプトは自動的に置き換わりません。更新後にサンプルが動かなくなった場合は、現在のアプリに付属するサンプルを復元して、もう一度実行してみてください。
編集したサンプルを先にバックアップしてから、「設定 → サンプルスクリプトを復元」を選んでください。examples フォルダ内の同名のサンプルファイルが上書きされます。
サンプルを復元しても、インストール済みの Python パッケージはリセットされません。依存パッケージのバージョン競合が続く場合は、エラーに記載されたパッケージのバージョンを確認してください。
依存パッケージの競合について編集と実行
コードの入力中にクラッシュする場合は？
エディタでコードを入力すると繰り返しクラッシュする場合、コード補完に関連している可能性があります。「設定 → コード補完」で「候補を自動表示」をオフにし、同じファイルでもう一度入力して、引き続きクラッシュするか確認してください。
問題を報告する際は、原因となるコード片、具体的な入力手順、および「候補を自動表示」をオフにしてもクラッシュするかどうかを添えてください。
「停止」を押してもすぐに停止しないのはなぜですか？
「停止」は実行中のコードに中断を要求しますが、すべての処理をすぐに中断できるわけではありません。time.sleep()、ネットワーク応答やロックの待機、一部のネイティブライブラリの計算は、処理が戻ってから停止します。モジュールのインポート中も、インポートが終わるまで待ちます。
しばらく待っても停止しない場合は、ファイルを保存してから iOS のアプリスイッチャーで Pythona を終了し、開き直してください。
スクリプトの実行中にアプリが終了するのはなぜですか？
終了関数
スクリプトが quit()、exit()、sys.exit() の呼び出しで実行を終了すると、デフォルトでは Pythona 全体が終了します。
「設定 → quit() / exit()」で「Pythonaを終了」を「現在の実行のみ終了」に変更すると、アプリを開いたまま現在の実行だけを終了できます。
メモリ不足
大きな配列の処理や大きなモデルの実行でメモリ使用量が増えすぎると、iOS がアプリを直接終了させることがあります。Python のエラーが表示されるとは限りません。この終了は「quit() / exit()」の設定では制御できません。データ量やモデルの規模を小さくするか、データを分割して処理してみてください。
UIKit のスレッド
Pythona の Python スクリプトは、デフォルトでバックグラウンドスレッドで実行されます。ctypes や rubicon-objc から UIKit を呼び出す場合、画面の作成や更新などの操作は iOS のメインスレッド（UI スレッド）で行う必要があります。別のスレッドで行うと、アプリがクラッシュすることがあります。
組み込みの run_on_ui(...) を使うと、これらの操作をまとめた関数をメインスレッドで非同期に実行できます。GCD を使って直接メインキューに送ることもできます。アプリ内の WKWebView サンプルに run_on_ui の使用例があります。
問題が繰り返し発生する場合は、再現できるコードと操作手順を添えて報告してください。
入力を終了して EOF を送信するには？
スクリプトの実行中に、コンソールの入力欄の編集メニューから「EOF を送信」を選ぶか、外付けキーボードで Ctrl+D を押します。入力欄に文字がある場合は先に送信され、その後、現在の実行への入力が終了します。
スクリプトに引数を渡すには？
エディタの実行ボタンを長押しし、「引数付きで実行…」を選択します。引数はスクリプトの sys.argv[1:] に渡されます。よく使う引数は、同じメニューの「実行構成を編集…」から保存し、デフォルトの構成に設定できます。
「ショートカット」アプリからスクリプトを実行するには？
エディタ上部のファイル名をタップし、「ショートカット」を選んで「スクリプトのパス」をコピーします。次に「ショートカット」アプリで Pythona の「Python スクリプトを実行」アクションを追加し、パスを入力します。必要に応じて引数を追加でき、アクションが返すテキスト出力は後続のアクションに渡せます。
ホーム画面からワンタップでスクリプトを実行するには？
Pythona でスクリプトを開き、エディタ上部のファイル名をタップして「ショートカット」を選び、「URL」をコピーします。
システムの「ショートカット」アプリで新しいショートカットを作成し、「URLを開く」アクションを追加して、コピーした URL を入力します。
そのショートカットの「詳細」で「ホーム画面に追加」を選び、名前とアイコンを設定して「追加」をタップします。
以後はホーム画面のアイコンをタップすると、Pythona が開いて対応するスクリプトが実行されます。
Apple の追加手順を見るライブラリと拡張機能
インストールできないサードパーティライブラリがあるのはなぜですか？
パッケージマネージャは、純粋な Python の wheel として配布されているサードパーティライブラリのインストールに対応しています。ソースコードのみで提供されるものや、C、C++、Rust などのコンパイル済み拡張を必要とするものは、パソコンと同じ方法では直接インストールできません。NumPy、SciPy などのネイティブライブラリは、事前にコンパイルしてアプリに同梱しています。
純粋な Python のライブラリでも、Python 3.14 と iOS への対応が必要です。この環境で利用できないシステム機能に依存する場合は、実行できないことがあります。
主な内蔵ライブラリを見るパッケージをインストールすると、依存パッケージのバージョンが変わったり競合が報告されたりするのはなぜですか？
すべてのプロジェクトは、そのデバイスのユーザーパッケージ環境を共有します。要件を満たす既存の依存パッケージはそのまま使用し、満たさない場合はユーザーがインストールした純粋な Python の依存パッケージをアップグレードまたはダウングレードすることがあります。アプリに内蔵されたパッケージは自動で置き換えません。
バージョンを変更する前に、ほかのインストール済みパッケージが宣言する関連の依存要件を確認します。競合や処理できない要件が見つかると、理由を示して停止します。すべてのバージョンの組み合わせを試すわけではなく、すべての互換性の問題を検出できるわけでもありません。
互換性のあるバージョンを指定するか、不要になった競合パッケージをアンインストールして再試行できます。また、Python スクリプトを自分で書き、純粋な Python パッケージのダウンロード、配置、依存関係の管理を行うこともできます。pythona.packages.install() の呼び出しにも上記のルールが適用され、手動インストールにも Python と iOS の互換性の制限があります。インポート済みのパッケージを置き換えた後は、Pythona を再起動してください。
インストールしたライブラリは iCloud で同期されますか？
同期されません。パッケージマネージャでインストールしたライブラリは、このデバイスのローカルフォルダに保存されます。ローカル、iCloud、外部フォルダにあるスクリプトから共通で利用できます。
iCloud でプロジェクトを同期した後も、別のデバイスにはプロジェクトが必要とするライブラリを個別にインストールしてください。
Pythona にはどんな iOS 向けライブラリがあり、どう使えますか？
Pythona には cocoa-py が組み込まれています。scene は、ゲーム、アニメーション、インタラクティブなグラフィックスに使えます。photos ではシステムの写真ピッカーから写真やビデオを選択したり、写真ライブラリに保存したりできます。audio は音声の再生、録音、エフェクト処理を提供し、coreml は Core ML モデルを読み込んでデバイス上で推論を実行します。
pythona からはアプリ自体の機能を利用できます。pythona.packages でサードパーティパッケージをインストールし、pythona.ai でカスタム AI プロバイダの設定を作成、取得、更新できます。
さらに iOS のシステム機能を使う場合は、rubicon-objc で Python から iOS のネイティブ API を呼び出す方法をおすすめします。UIKit を使ってネイティブな画面を作ることもできます。アプリ内のデバイス情報と WKWebView のサンプルを参照してください。
cocoa-py はオープンソースで、macOS にも対応しています。利用できる機能はプラットフォームによって異なります。ソースコードと API ドキュメントは GitHub で公開しており、Issue やプルリクエストも歓迎します。
cocoa-py のソースコードとドキュメントを見るゲームや GUI を作るには何を使えばよいですか？
2D ゲーム、アニメーション、音声再生には pygame をおすすめします（アプリには pygame-ce が組み込まれています）。pygame.mixer だけを使えば、ウィンドウを作らずに音楽や効果音を再生できます。
画面や Web ゲームは HTML、CSS、JavaScript で作成し、Pythona 内では WKWebView で表示できます。Web コンテンツは他のプラットフォームでも再利用しやすい一方、WKWebView を表示するコードや、ページと Python・iOS の機能をつなぐ処理は、移行先の環境に合わせた調整が必要です。
iOS のネイティブな画面が必要な場合は、rubicon-objc から UIKit を呼び出せます。UIKit を使うコードは引き続き iOS に依存します。
Pythona は Tkinter にも対応しており、既存の Tkinter スクリプトの実行や簡単なツールの作成に使えます。従来のデスクトップアプリに近い見た目のため、モバイルでの見た目や操作性を重視する場合は、Web ベースの画面や rubicon-objc 経由の UIKit をおすすめします。アプリ内にサンプルがあります。
ファイル
パソコンとファイルをやり取りするには？
コードのプロジェクトには Git をおすすめします。Pythona とパソコンで同じリモートリポジトリをクローンし、変更をコミットしてプッシュした後、もう一方でプルして更新を取り込みます。
iCloud Drive でファイルを同期したり、システムの共有機能で書き出したりすることもできます。Mac とのやり取りには AirDrop も使えます。
アプリで「ファイルサーバー」を有効にすると、同じローカルネットワークに接続したパソコンのブラウザで、アプリに表示されたアドレスにアクセスしてファイルをアップロード、ダウンロードできます。ファイルサーバーにログイン用パスワードはありません。信頼できるネットワークで使用し、転送が終わったらサーバーを停止してください。
AI
Python ではどのようなローカル AI モデルを使えますか？
MLX：アプリに内蔵された MLX と mlx-lm を組み合わせて、対応する言語モデルを実行できます。アプリ内の examples/llm_demo.py を参照してください。初回実行時にインターネット経由で依存パッケージをインストールし、Hugging Face からモデルをダウンロードします。MLX に対応し、十分なメモリを備えたデバイスが必要です。実行速度と利用できるモデルの規模は、デバイスの性能とメモリに依存します。
Apple Foundation Models：内蔵の apple-fm-sdk を使って、Apple が提供するオンデバイスモデルを呼び出せます。Python では import apple_fm_sdk でインポートします。iOS / iPadOS 26 以降、Apple Intelligence に対応し有効にしたデバイス、利用準備が完了したシステムモデルが必要です。利用可否は言語や地域にも依存します。API の使い方は下記のドキュメントを参照してください。
どちらもモデルの推論はデバイス上で行われます。依存パッケージやモデルのダウンロードにはインターネット接続が必要です。スクリプトやアシスタントのツールがオンラインサービスを利用する場合も、ネットワークにアクセスします。
Foundation Models Python SDK の使い方を見るローカルモデルを AI アシスタントに接続するには？
オープンソースの Pythona AI Setup を使うと、Apple Foundation Models や MLX のローカルモデル用に AI アシスタントの設定を作成できます。
Pythona でプロジェクトをクローンし、プロジェクトのルートにある main.py を実行します。ページの案内に従ってモデルとツールを選び、設定を追加したら、AI アシスタントの設定でその接続を選択してください。詳しい手順はプロジェクトの README を参照してください。
ファイルの読み書きや Python の実行など、アシスタントのツールを使うには、MLX モデルがツール呼び出しに対応している必要があります。非対応のモデルも、すべてのツールを無効にすれば会話に利用できます。
Pythona AI Setup と使い方を見るAI アシスタントはどのファイルを読み書きできますか？
AI アシスタントは、現在の会話のワークスペースをデフォルトのプロジェクトディレクトリとして使用します。新しい会話で最初のメッセージを送る前に、「ワークスペースを変更」からフォルダを選択できます。ファイルブラウザで別のディレクトリに移動しても、既存の会話のワークスペースは変わりません。
AI アシスタントは run_python を呼び出して Python コードを実行し、ワークスペース外の内容を含む、アプリ内のファイルやフォルダを読み取ることもできます。このアクセスは、選択したワークスペースの範囲に制限されません。
AI アシスタントは AGENTS.md に対応していますか？
はい。現在の会話のワークスペースのルートに AGENTS.md を作成すると、プロジェクトの説明、コーディング規約、その他の共同作業のルールを記載できます。
アシスタントは新しいメッセージを処理するたびに、このファイルを自動で読み取ります。変更を保存すると、次にメッセージを送信したときに反映されます。自動で読み込むのはワークスペースのルートにある AGENTS.md のみで、サブディレクトリの同名ファイルは自動で統合されません。
カスタムプロバイダ（JS Provider）は何に使えますか？
カスタムプロバイダでは、JavaScript で AI サービスへの接続方法をカスタマイズできます。組み込みプロバイダがまだ対応していない API、認証方式、サービス機能を利用したり、カスタムツールを追加したりできます。
ここで JavaScript を使うのは、AI サービスへの接続、認証、レスポンスの処理を独立した実行環境で行い、こうした連携処理がユーザーの Python 環境に影響しないようにするためです。
カスタムツールからは外部サービスを呼び出せるほか、run_python を組み込むことで、アシスタントが Python スクリプトを実行したり、スクリプトを通じて iOS の機能を使ったりできます。
組み込みプロバイダで必要なことができる場合、追加の設定は不要です。機能を拡張したい場合は、設定画面の JavaScript API とサンプルを参照してください。
購入と復元
別のデバイスでも Pro を購入し直す必要がありますか？
必要ありません。ほかのデバイスでも、購入時と同じ Apple Account で App Store にサインインすれば、購入済みの Pro を引き続き利用できます。
新しいデバイスへの Pythona のインストール後や再インストール後も試用の案内や購入画面が表示される場合、購入状況がまだ同期されていない可能性があります。インターネットに接続し、購入画面で「購入を復元」をタップしてください。
購入の復元に料金はかかりません。購入ボタンをもう一度タップしても、同じ Apple Account で購入済みの同じ Pro に対して重複して請求されることはありません。
Apple Account の切り替え後に Pro が使えないのはなぜですか？
Pro の購入は、購入時に App Store で使用した Apple Account に関連付けられています。Pro を購入していない別のアカウントに切り替えると、Pro を利用できなくなる場合があります。App Store で購入時のアカウントに戻し、Pythona で「購入を復元」をタップしてください。
App Store のアカウントを頻繁に切り替えることで Pythona の利用に支障がある場合は、お問い合わせください。