Perguntas frequentes

As atualizações do app não substituem automaticamente os scripts de exemplo já salvos. Se um exemplo parar de funcionar após uma atualização, restaure os exemplos incluídos na versão atual e tente executá-lo novamente.

Faça primeiro uma cópia dos exemplos que você modificou. Depois, acesse “Ajustes → Restaurar scripts de exemplo”. A restauração substitui os arquivos de exemplo com o mesmo nome na pasta examples.

Restaurar os exemplos não redefine os pacotes Python instalados. Se ainda houver conflitos de dependências, confira as versões dos pacotes indicados na mensagem de erro.

Parar solicita a interrupção da execução atual, mas nem todas as operações podem ser interrompidas imediatamente. É preciso aguardar o retorno de chamadas como time.sleep(), esperas de rede ou de bloqueios e alguns cálculos em bibliotecas nativas. Durante a importação de um módulo, a interrupção também aguarda o fim da importação.

Se a execução demorar muito para parar, salve seus arquivos, feche o Pythona pelo seletor de apps do iOS e abra-o novamente.

Por padrão, quando um script termina com quit(), exit() ou sys.exit(), o Pythona fecha o app inteiro.

Em “Ajustes → quit() / exit()”, troque “Sair do Pythona” por “Encerrar execução atual” para encerrar apenas a execução e manter o app aberto.

Ao processar arrays grandes ou executar modelos grandes, o uso excessivo de memória pode levar o iOS a encerrar o app sem exibir um erro Python. Esse encerramento não é controlado pelo ajuste “quit() / exit()”. Tente reduzir o tamanho dos dados ou do modelo, ou processar os dados em lotes.

Se o problema se repetir, envie o código e os passos necessários para reproduzi-lo.

Durante a execução de um script, escolha “Enviar EOF” no menu de edição do campo de entrada do console ou pressione Ctrl+D em um teclado externo. O texto no campo é enviado primeiro; depois, a entrada da execução atual é encerrada.

Mantenha pressionado o botão de executar no editor e escolha “Executar com argumentos”. Os argumentos são passados ao script em sys.argv[1:]. Para salvar argumentos usados com frequência e definir uma configuração padrão, escolha “Editar configurações de execução...” no mesmo menu.

No editor, toque no nome do arquivo na parte superior, escolha “Atalhos” e copie o “Caminho do script”. No app Atalhos do sistema, adicione a ação “Executar script Python” do Pythona e cole o caminho. Você também pode adicionar argumentos e usar a saída de texto retornada pela ação nas ações seguintes.

O gerenciador de pacotes instala bibliotecas de terceiros distribuídas como wheels em Python puro. Algumas bibliotecas só oferecem código-fonte ou dependem de extensões compiladas em C, C++, Rust ou outras linguagens e não podem ser instaladas diretamente como em um computador. Bibliotecas nativas como NumPy e SciPy já vêm pré-compiladas no app.

Mesmo as bibliotecas em Python puro precisam ser compatíveis com Python 3.14 e iOS. Se dependerem de recursos do sistema indisponíveis neste ambiente, ainda poderão não funcionar.

Todos os projetos compartilham o ambiente de pacotes do usuário no dispositivo atual. A instalação reutiliza as dependências existentes que atendem aos requisitos. Quando isso não é possível, ela pode substituir dependências em Python puro instaladas pelo usuário por versões mais recentes ou mais antigas. Os pacotes incluídos no app não são substituídos automaticamente.

Antes de alterar uma versão, o instalador verifica os requisitos de dependências correspondentes declarados pelos outros pacotes instalados. Se encontrar um conflito ou um requisito que não consiga resolver, ele para e explica o motivo. O instalador não testa todas as combinações de versões nem consegue detectar todos os problemas de compatibilidade.

Você pode especificar uma versão compatível, desinstalar pacotes conflitantes que não usa mais e tentar novamente, ou escrever seus próprios scripts Python para baixar, instalar e gerenciar pacotes em Python puro e suas dependências. Chamadas a pythona.packages.install() seguem as mesmas regras. A instalação manual também está sujeita às limitações de compatibilidade do Python e do iOS. Reinicie o Pythona após substituir um pacote que já tenha sido importado.

Não. As bibliotecas instaladas pelo gerenciador de pacotes ficam apenas no dispositivo atual. Scripts armazenados localmente, no iCloud ou em pastas externas podem usar essas bibliotecas.

Depois de sincronizar um projeto pelo iCloud, instale suas dependências separadamente no outro dispositivo.

O Pythona inclui cocoa-py: scene oferece jogos, animações e gráficos interativos; photos permite selecionar ou salvar fotos e vídeos pela biblioteca de fotos do sistema; audio oferece reprodução, gravação e efeitos de áudio; coreml carrega modelos Core ML e executa inferência no dispositivo.

Use pythona para acessar recursos do próprio app: pythona.packages instala pacotes de terceiros, e pythona.ai cria, lê e atualiza configurações de provedores de IA personalizados.

Para acessar outros recursos do sistema, recomendamos rubicon-objc, que permite chamar APIs nativas do iOS a partir do Python, inclusive criar interfaces nativas com UIKit. Veja os exemplos de informações do dispositivo e WKWebView incluídos no app.

cocoa-py tem código aberto e também é compatível com macOS; os recursos disponíveis variam conforme a plataforma. O código-fonte e a documentação da API estão no GitHub, onde você pode enviar issues e pull requests.

Para jogos 2D, animações e reprodução de áudio, recomendamos pygame. O app inclui pygame-ce. Você pode usar pygame.mixer para reproduzir músicas ou efeitos sonoros sem criar uma janela.

Para criar interfaces ou jogos web, use HTML, CSS e JavaScript e exiba o conteúdo no Pythona com WKWebView. O conteúdo web pode ser reutilizado em outras plataformas. Ao fazer a adaptação, ajuste o código que exibe o WKWebView e a comunicação da página com Python ou com os recursos do iOS.

Para interfaces nativas do iOS, use rubicon-objc para chamar UIKit. O código que usa UIKit continua dependendo do iOS.

O Pythona também oferece suporte a Tkinter para executar scripts existentes ou criar ferramentas simples. A interface segue o estilo tradicional de aplicativos de computador. Se a aparência e a interação em dispositivos móveis forem a prioridade, prefira uma interface web ou UIKit via rubicon-objc. O app inclui exemplos dessas opções.

Para projetos de código, recomendamos Git: clone o mesmo repositório remoto no Pythona e no computador. Após fazer alterações, crie um commit e envie-o ao repositório remoto. Depois, obtenha as atualizações no outro dispositivo.

Você pode sincronizar arquivos pelo iCloud Drive ou exportá-los com o compartilhamento do sistema. Para trocar arquivos com um Mac, também pode usar AirDrop.

Outra opção é iniciar o “Servidor de arquivos” no app. Em um computador na mesma rede local, abra no navegador o endereço exibido para enviar e baixar arquivos. O servidor não tem senha de acesso: use-o em uma rede confiável e pare o serviço após a transferência.

MLX: o app inclui MLX, que pode ser usado com mlx-lm para executar modelos de linguagem compatíveis. Veja examples/llm_demo.py no app. Na primeira execução, o exemplo usa a internet para instalar dependências e baixar um modelo do Hugging Face. O dispositivo precisa ser compatível com MLX e ter memória suficiente. A velocidade de execução e o tamanho dos modelos possíveis dependem do desempenho e da memória do dispositivo.

Apple Foundation Models: use o apple-fm-sdk incluído no app para acessar os modelos da Apple executados no dispositivo. Em Python, importe-o com import apple_fm_sdk. É necessário iOS / iPadOS 26 ou posterior, um dispositivo compatível com Apple Intelligence e com esse recurso ativado, além dos modelos do sistema prontos para uso. A disponibilidade também depende do idioma e da região. Consulte a documentação abaixo para usar a API.

Nos dois casos, a inferência é executada no dispositivo. Baixar dependências e modelos exige conexão com a internet. Scripts ou o assistente também acessam a rede ao chamar ferramentas que precisam de conexão.

Use o projeto de código aberto Pythona AI Setup para criar configurações do assistente de IA com Apple Foundation Models ou modelos locais do MLX.

Clone o projeto no Pythona, execute main.py na raiz do projeto, siga as instruções para escolher o modelo e as ferramentas e adicione a configuração. Depois, selecione a conexão correspondente nos ajustes do assistente de IA. As etapas detalhadas estão no README do projeto.

Modelos do MLX precisam oferecer suporte a chamadas de ferramentas para que o assistente possa ler e gravar arquivos ou executar Python. Modelos sem esse suporte podem ser usados para conversar com todas as ferramentas desativadas.

O assistente de IA usa o espaço de trabalho da conversa atual como pasta padrão do projeto. Antes de enviar a primeira mensagem de uma nova conversa, escolha uma pasta em “Alterar espaço de trabalho”. Mudar de pasta no explorador de arquivos não altera o espaço de trabalho de uma conversa existente.

O assistente também pode chamar run_python para executar código Python e ler arquivos e pastas do app, inclusive fora do espaço de trabalho. Esse acesso não fica limitado à pasta selecionada como espaço de trabalho.

Sim. Crie um arquivo AGENTS.md na raiz do espaço de trabalho da conversa atual para incluir informações sobre o projeto, estilo de código e outras instruções de colaboração.

O assistente lê esse arquivo automaticamente ao processar cada nova mensagem. Depois de salvar uma alteração, ela entra em vigor na próxima mensagem enviada. Apenas o AGENTS.md da raiz do espaço de trabalho é carregado automaticamente; arquivos com o mesmo nome em subpastas não são combinados automaticamente.

Um provedor personalizado permite conectar serviços de IA usando JavaScript. Você pode usar APIs, métodos de autenticação ou recursos ainda não disponíveis nos provedores integrados, além de adicionar ferramentas próprias.

O JavaScript mantém a conexão, a autenticação e o processamento das respostas dos serviços de IA em um ambiente de execução separado, para não interferir no seu ambiente Python.

As ferramentas personalizadas podem chamar serviços externos ou usar run_python para que o assistente execute scripts Python e, por meio deles, acesse recursos do iOS.

Se os provedores integrados já atendem às suas necessidades, não é preciso configurar nada a mais. Para estender as funcionalidades, consulte a API JavaScript e os exemplos na página de configuração.