Como instalar Kivy e criar seu primeiro app multiplataforma em Python

Imagine criar um app que roda no seu computador e no celular usando exatamente o mesmo código Python. Parece complicado? Na verdade, com a instalação do Kivy, você consegue fazer isso em apenas 15 minutos.

Ao final deste tutorial, você terá o Kivy instalado corretamente no seu sistema e criará um app funcional com botões, textos e interações básicas. Melhor ainda, você precisará apenas de conhecimento básico em Python para acompanhar.

Ainda em dúvida se Kivy é para você? Veja nossa análise completa sobre quando vale a pena usar Kivy.

Pré-requisitos para instalar Kivy: preparando o ambiente

Antes de instalar o Kivy, vamos garantir que seu ambiente esteja preparado.

Primeiramente, precisamos verificar se os componentes essenciais estão funcionando. Em seguida, vamos configurar algumas ferramentas opcionais que, por sua vez, facilitarão muito seu desenvolvimento.

Checklist obrigatório

python --version
pip --version

python --version
pip --version

Dica importante: sempre use ambientes virtuais para projetos Python, que são como ter gavetas separadas para cada projeto. Dessa maneira, evita bagunça e conflitos entre bibliotecas.

Leia também:

Ambientes virtuais em Python: o que são e como criar no Windows e VS Code

Como instalar o Kivy: passo a passo Windows, macOS e Linux

Agora vamos ao que interessa: como instalar o Kivy. Visto que cada sistema operacional tem suas particularidades, portanto, separei instruções específicas para cada um.

Instalar Kivy no Windows

Método 1: instalação direta (recomendado):

# Abrir PowerShell como administrador
pip install kivy

# Verificar instalação
python -c "import kivy; print(kivy.__version__)"

# Abrir PowerShell como administrador
pip install kivy

# Verificar instalação
python -c "import kivy; print(kivy.__version__)"

Contudo, se der problema, então use o método 2:

# Primeiramente, instalar dependências
pip install kivy.deps.sdl2 kivy.deps.glew kivy.deps.angle

# Logo depois, instalar Kivy
pip install kivy

# Primeiramente, instalar dependências
pip install kivy.deps.sdl2 kivy.deps.glew kivy.deps.angle

# Logo depois, instalar Kivy
pip install kivy

Similarmente, para usuários Anaconda:

conda install kivy -c conda-forge

conda install kivy -c conda-forge

Instalar Kivy no macOS

Agora é necessário instalar as dependências:

# Instalar Homebrew (se não tiver)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Em seguida, instalar dependências
brew install sdl2 sdl2_image sdl2_ttf sdl2_mixer

# Por fim, instalar Kivy
pip install kivy

# Instalar Homebrew (se não tiver)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Em seguida, instalar dependências
brew install sdl2 sdl2_image sdl2_ttf sdl2_mixer

# Por fim, instalar Kivy
pip install kivy

Ademais, para Macs com chip M1/M2:

export KIVY_GL_BACKEND=angle_sdl2
pip install kivy

export KIVY_GL_BACKEND=angle_sdl2
pip install kivy

Instalar Kivy no Linux (Ubuntu/Debian)

Dependências do sistema para o Linux:

# Primeiramente, atualizar repositórios
sudo apt update

# Em seguida, instalar dependências essenciais
sudo apt install -y \
    python3-pip \
    build-essential \
    git \
    python3-dev \
    libsdl2-dev \
    libsdl2-image-dev \
    libsdl2-mixer-dev \
    libsdl2-ttf-dev

# Primeiramente, atualizar repositórios
sudo apt update

# Em seguida, instalar dependências essenciais
sudo apt install -y \
    python3-pip \
    build-essential \
    git \
    python3-dev \
    libsdl2-dev \
    libsdl2-image-dev \
    libsdl2-mixer-dev \
    libsdl2-ttf-dev

Finalmente, instalar Kivy:

pip3 install kivy

pip3 install kivy

Verificação da instalação

Conforme esperado, teste rápido para todos os sistemas:

# Criar arquivo: test_kivy.py
from kivy.app import runTouchApp
from kivy.uix.button import Button

runTouchApp(Button(text="Olá Mundo!"))

# Criar arquivo: test_kivy.py
from kivy.app import runTouchApp
from kivy.uix.button import Button

runTouchApp(Button(text="Olá Mundo!"))

Se aparecer uma janela com um botão grande escrito “Olá Mundo!”, parabéns! Assim, sua instalação está perfeita.

Troubleshooting: solucionando erros de instalação do Kivy

Nem sempre tudo sai como esperado na primeira tentativa, por isso reuni aqui as soluções para os problemas mais comuns. Então, considere esta seção seu “kit de primeiros socorros” para instalação.

Erro: “Microsoft Visual C++ 14.0 is required” (Windows)

Solução:

1. Em primeiro lugar, baixe e instale Microsoft C++ Build Tools;
2. Por outro lado, use versão pré-compilada: “pip install –only-binary=all kivy”.

Erro: “No module named ‘_ctypes'” (Linux)

Solução rápida:

sudo apt-get install libffi-dev python3-dev

sudo apt-get install libffi-dev python3-dev

Eventualmente, app abre mas tela fica preta

Diagnóstico e solução:

# Adicionar no início do seu código
from kivy.config import Config
Config.set("graphics", "multisamples", "0")

# Adicionar no início do seu código
from kivy.config import Config
Config.set("graphics", "multisamples", "0")

Dicas gerais de troubleshooting

Ainda com problemas? A comunidade Kivy no Discord é muito ativa e responsiva.

Arquitetura básica do Kivy: entenda antes de codar

Agora que você instalou o Kivy, entenda como ele funciona antes de começar a codar.

Estrutura de um app Kivy

Todo app Kivy tem três componentes fundamentais. Igualmente, pense neles como os ingredientes básicos de uma receita:

from kivy.app import App
from kivy.uix.button import Button

class MeuApp(App):          # 1. Classe App (herda de App)
    def build(self):        # 2. Método build (retorna widget raiz)
        return Button(text="Olá Mundo!")  # 3. Widget raiz

MeuApp().run()  # Executa o app

from kivy.app import App
from kivy.uix.button import Button

class MeuApp(App):          # 1. Classe App (herda de App)
    def build(self):        # 2. Método build (retorna widget raiz)
        return Button(text="Olá Mundo!")  # 3. Widget raiz

MeuApp().run()  # Executa o app

Widgets: os blocos de construção

Widgets são como peças de LEGO, em que cada um tem uma função específica, e você os combina para criar interfaces complexas.

Hierarquia típica:

App
└── BoxLayout (raiz)
    ├── Button
    ├── Label  
    └── TextInput

App
└── BoxLayout (raiz)
    ├── Button
    ├── Label  
    └── TextInput

Sistema de eventos: criando interatividade

O sistema de eventos no Kivy é como um sistema de notificações: você “assina” eventos específicos e recebe avisos quando eles acontecem.

def quando_clicado(instance):
    print(f"Botão {instance.text} foi clicado!")

botao = Button(text="Clique aqui")
botao.bind(on_press=quando_clicado)  # "Assina" o evento

def quando_clicado(instance):
    print(f"Botão {instance.text} foi clicado!")

botao = Button(text="Clique aqui")
botao.bind(on_press=quando_clicado)  # "Assina" o evento

Sistema de tamanhos

O Kivy tem duas maneiras de definir tamanhos: proporcionais e absolutos.

size_hint: proporção relativa (0-1)

# Botão ocupa 50% da largura e 30% da altura do pai
Button(text="Responsivo", size_hint=(0.5, 0.3))

# Botão ocupa 50% da largura e 30% da altura do pai
Button(text="Responsivo", size_hint=(0.5, 0.3))

size: pixels absolutos

# Botão com tamanho fixo
Button(text="Fixo", size_hint=(None, None), size=(200, 100))

# Botão com tamanho fixo
Button(text="Fixo", size_hint=(None, None), size=(200, 100))

Hands-on: criando uma lista de lembrete funcional

Agora vamos criar algo útil! Nosso primeiro app será uma lista de lembretes simples, mas funcional.

O que vamos criar

Nosso aplicativo permitirá:

• Adicionar novos lembretes facilmente;
• Visualizar a lista de lembretes;
• Remover lembretes concluídos.

Tudo isso com uma interface simples e intuitiva.

Passo 1: estrutura básica

Vamos começar criando a base do nosso app:

from kivy.app import App
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.button import Button
from kivy.uix.textinput import TextInput
from kivy.uix.label import Label

class ListaLembretesApp(App):
    def build(self):
        # Layout principal (vertical)
        layout_principal = BoxLayout(orientation="vertical", padding=10, spacing=10)
        
        # Título do app
        titulo = Label(text="Minha Lista de Lembretes", 
                      size_hint=(1, 0.1),
                      font_size="20sp")
        
        return layout_principal

# Para testar: ListaLembretesApp().run()

from kivy.app import App
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.button import Button
from kivy.uix.textinput import TextInput
from kivy.uix.label import Label

class ListaLembretesApp(App):
    def build(self):
        # Layout principal (vertical)
        layout_principal = BoxLayout(orientation="vertical", padding=10, spacing=10)
        
        # Título do app
        titulo = Label(text="Minha Lista de Lembretes", 
                      size_hint=(1, 0.1),
                      font_size="20sp")
        
        return layout_principal

# Para testar: ListaLembretesApp().run()

Passo 2: adicionando funcionalidades

Agora vamos adicionar a capacidade de criar e gerenciar lembretes:

class ListaLembretesApp(App):
    def __init__(self):
        super().__init__()
        self.lembretes = []  # Lista para armazenar lembretes
    
    def build(self):
        # Layout principal
        self.layout_principal = BoxLayout(orientation="vertical", padding=10, spacing=10)
        
        # Título
        titulo = Label(text="Meus Lembretes", 
                      size_hint=(1, 0.1),
                      font_size="24sp")
        
        # Campo para novo lembrete
        layout_entrada = BoxLayout(orientation="horizontal", size_hint=(1, 0.1))
        
        self.campo_texto = TextInput(hint_text="Digite seu lembrete aqui...",
                                   size_hint=(0.8, 1))
        
        botao_adicionar = Button(text="Adicionar",
                               size_hint=(0.2, 1))
        botao_adicionar.bind(on_press=self.adicionar_lembrete)
        
        # Área dos lembretes
        self.area_lembretes = BoxLayout(orientation="vertical", size_hint=(1, 0.8))
        
        # Montando a interface
        layout_entrada.add_widget(self.campo_texto)
        layout_entrada.add_widget(botao_adicionar)
        
        self.layout_principal.add_widget(titulo)
        self.layout_principal.add_widget(layout_entrada)
        self.layout_principal.add_widget(self.area_lembretes)
        
        return self.layout_principal

class ListaLembretesApp(App):
    def __init__(self):
        super().__init__()
        self.lembretes = []  # Lista para armazenar lembretes
    
    def build(self):
        # Layout principal
        self.layout_principal = BoxLayout(orientation="vertical", padding=10, spacing=10)
        
        # Título
        titulo = Label(text="Meus Lembretes", 
                      size_hint=(1, 0.1),
                      font_size="24sp")
        
        # Campo para novo lembrete
        layout_entrada = BoxLayout(orientation="horizontal", size_hint=(1, 0.1))
        
        self.campo_texto = TextInput(hint_text="Digite seu lembrete aqui...",
                                   size_hint=(0.8, 1))
        
        botao_adicionar = Button(text="Adicionar",
                               size_hint=(0.2, 1))
        botao_adicionar.bind(on_press=self.adicionar_lembrete)
        
        # Área dos lembretes
        self.area_lembretes = BoxLayout(orientation="vertical", size_hint=(1, 0.8))
        
        # Montando a interface
        layout_entrada.add_widget(self.campo_texto)
        layout_entrada.add_widget(botao_adicionar)
        
        self.layout_principal.add_widget(titulo)
        self.layout_principal.add_widget(layout_entrada)
        self.layout_principal.add_widget(self.area_lembretes)
        
        return self.layout_principal

Métodos de interação

Agora vamos implementar a lógica de adicionar e remover lembretes:

    def adicionar_lembrete(self, instance):
        texto = self.campo_texto.text.strip()
        if texto:  # Só adiciona se não estiver vazio
            self.criar_item_lembrete(texto)
            self.campo_texto.text = ""  # Limpa o campo
    
    def criar_item_lembrete(self, texto):
        # Layout para cada lembrete individual
        item_layout = BoxLayout(orientation="horizontal", size_hint=(1, None), height=50)
        
        # Texto do lembrete
        label_lembrete = Label(text=texto, size_hint=(0.8, 1))
        
        # Botão para remover
        botao_remover = Button(text="Feito", size_hint=(0.2, 1))
        botao_remover.bind(on_press=lambda x: self.remover_lembrete(item_layout))
        
        item_layout.add_widget(label_lembrete)
        item_layout.add_widget(botao_remover)
        
        # Adiciona à área de lembretes
        self.area_lembretes.add_widget(item_layout)
        self.lembretes.append(item_layout)
    
    def remover_lembrete(self, item_layout):
        self.area_lembretes.remove_widget(item_layout)
        self.lembretes.remove(item_layout)

# Executar o app
ListaLembretesApp().run()

    def adicionar_lembrete(self, instance):
        texto = self.campo_texto.text.strip()
        if texto:  # Só adiciona se não estiver vazio
            self.criar_item_lembrete(texto)
            self.campo_texto.text = ""  # Limpa o campo
    
    def criar_item_lembrete(self, texto):
        # Layout para cada lembrete individual
        item_layout = BoxLayout(orientation="horizontal", size_hint=(1, None), height=50)
        
        # Texto do lembrete
        label_lembrete = Label(text=texto, size_hint=(0.8, 1))
        
        # Botão para remover
        botao_remover = Button(text="Feito", size_hint=(0.2, 1))
        botao_remover.bind(on_press=lambda x: self.remover_lembrete(item_layout))
        
        item_layout.add_widget(label_lembrete)
        item_layout.add_widget(botao_remover)
        
        # Adiciona à área de lembretes
        self.area_lembretes.add_widget(item_layout)
        self.lembretes.append(item_layout)
    
    def remover_lembrete(self, item_layout):
        self.area_lembretes.remove_widget(item_layout)
        self.lembretes.remove(item_layout)

# Executar o app
ListaLembretesApp().run()

Testando o app

Salve o código acima em um arquivo chamado “lista_lembretes.py” e execute:

python lista_lembretes.py

python lista_lembretes.py

Evoluindo o app: cores, fontes e efeitos visuais

Nesta segunda etapa, podemos deixar a nossa interface ainda mais bonita.

Customizando cores e aparência

Após fazer a estrutura, vamos adicionar algumas melhorias visuais ao nosso app. Inicialmente, trabalharemos com cores personalizadas:

from kivy.utils import get_color_from_hex

class ListaLembretesApp(App):
    def build(self):
        # Cores personalizadas
        cor_fundo = get_color_from_hex("#2C3E50")  # Azul escuro
        cor_botao = get_color_from_hex("#3498DB")   # Azul claro
        cor_sucesso = get_color_from_hex("#27AE60") # Verde
        
        # Layout principal com cor de fundo
        from kivy.lang.builder import Builder
        from textwrap import dedent
        self.layout_principal = Builder.load_string(dedent(f"""
            <Button>:
                background_color: {cor_botao}

            <Label>:
                canvas.before:
                    Color:
                        rgba: {cor_sucesso}
                    Rectangle:
                        size: self.size
                        pos: self.pos

            BoxLayout:
                orientation: "vertical"
                padding: 15
                spacing: 10
                canvas.before:
                    Color:
                        rgba: {cor_fundo}
                    Rectangle:
                        size: self.size
                        pos: self.pos
        """))
        
        # Título estilizado
        titulo = Label(text="Meus Lembretes", 
                      size_hint=(1, 0.12),
                      font_size="28sp",
                      bold=True,
                      color=get_color_from_hex("#ECF0F1"))

from kivy.utils import get_color_from_hex

class ListaLembretesApp(App):
    def build(self):
        # Cores personalizadas
        cor_fundo = get_color_from_hex("#2C3E50")  # Azul escuro
        cor_botao = get_color_from_hex("#3498DB")   # Azul claro
        cor_sucesso = get_color_from_hex("#27AE60") # Verde
        
        # Layout principal com cor de fundo
        from kivy.lang.builder import Builder
        from textwrap import dedent
        self.layout_principal = Builder.load_string(dedent(f"""
            <Button>:
                background_color: {cor_botao}

            <Label>:
                canvas.before:
                    Color:
                        rgba: {cor_sucesso}
                    Rectangle:
                        size: self.size
                        pos: self.pos

            BoxLayout:
                orientation: "vertical"
                padding: 15
                spacing: 10
                canvas.before:
                    Color:
                        rgba: {cor_fundo}
                    Rectangle:
                        size: self.size
                        pos: self.pos
        """))
        
        # Título estilizado
        titulo = Label(text="Meus Lembretes", 
                      size_hint=(1, 0.12),
                      font_size="28sp",
                      bold=True,
                      color=get_color_from_hex("#ECF0F1"))

Adicionando feedback visual

Agora vamos adicionar um pequeno detalhe na experiência do usuário:

def adicionar_lembrete(self, instance):
    texto = self.campo_texto.text.strip()
    if texto:
        self.criar_item_lembrete(texto)
        self.campo_texto.text = ""
        # Feedback visual temporário
        instance.text = "Adicionado!"
        Clock.schedule_once(lambda dt: setattr(instance, "text", "Adicionar"), 1)

def adicionar_lembrete(self, instance):
    texto = self.campo_texto.text.strip()
    if texto:
        self.criar_item_lembrete(texto)
        self.campo_texto.text = ""
        # Feedback visual temporário
        instance.text = "Adicionado!"
        Clock.schedule_once(lambda dt: setattr(instance, "text", "Adicionar"), 1)

Parabéns! Para onde ir agora?

Você acabou de dar um grande passo no mundo do desenvolvimento de aplicações multiplataforma!

Próximos desafios

Projetos sugeridos (ordem crescente de dificuldade):

1. Calculadora simples – primeiramente, pratique layouts e eventos;
2. Conversor de moedas – em seguida, integre APIs externas;
3. Jogo da velha – logo após, explore lógica de jogos;
4. App de notas – posteriormente, implemente persistência de dados;
5. Dashboard pessoal – finalmente, combine múltiplas funcionalidades.

Recursos para continuar aprendendo

Ferramentas profissionais:

• KivyMD: primeiramente, componentes Material Design;
• Buildozer: em seguida, compilação para Android/iOS;
• Kivy Garden: por fim, widgets extras da comunidade.

Próximo passo recomendado: explore nossa trilha completa de Python para desenvolvimento para, dessa forma, aprofundar seus conhecimentos.

Trilha Python para Web

Domine a programação Python para web de forma prática! Crie aplicações web e desenvolva seus próprios projetos com Python e Django.

Comece agora

FAQ – perguntas frequentes sobre Kivy

Posso usar este app comercialmente?

Certamente! Kivy usa licença MIT, permitindo uso comercial. Apenas mantenha os créditos da biblioteca nos seus projetos.

Como fazer o app funcionar no celular?

Basicamente, use Buildozer para Android ou kivy-ios para iPhone, mas é um processo mais avançado.

O app está lento, é normal?

Geralmente, apps Kivy podem ser ligeiramente mais lentos que aplicações nativas. No entanto, para apps simples como o que criamos, a performance deve ser excelente.

Tive problemas durante a instalação do Kivy, é normal?

Ocasionalmente, alguns problemas são comuns, especialmente relacionados a dependências do sistema.

Consulte nossa seção de troubleshooting, pois ela resolve 90% dos casos. Ademais, a comunidade Discord também é muito prestativa.