Espanso Não está funcionando? 9 soluções comuns (2026)

Espanso é um poderoso expansor de texto de código aberto, mas sua configuração baseada em YAML significa que as coisas podem dar errado de maneiras que não são óbvias. Aqui estão os motivos mais comuns pelos quais Espanso para de funcionar – e como consertar cada um deles. Para CLI e caminhos oficiais, consulte a documentação do Espanso.

Divulgação: fazemos Lightning Assist, um expansor de texto pago, então Espanso é um concorrente nosso. Espanso é gratuito e de código aberto, e todas as correções abaixo são para o próprio Espanso – nenhuma delas exige mudar para outra ferramenta.

Atualizado em 7 de setembro de 2026: correção #9 reescrita para Espanso 2.4.1 e Ubuntu 26.04, que não inclui mais uma sessão X11.

1. Espanso não está em execução

A causa mais comum: o serviço Espanso não foi iniciado.

Correção:

espanso start

Verifique se está funcionando:

espanso status

No Linux com systemd:

systemctl --user status espanso
systemctl --user start espanso

2. Erro de sintaxe YAML na sua configuração

Espanso falha silenciosamente quando um arquivo de configuração tem YAML inválido. Uma tabulação ou dois pontos mal colocados quebra o arquivo inteiro.

Correção: Execute o diagnóstico de configuração:

espanso doctor

Erros comuns a serem verificados:

• Usando tabulações em vez de espaços (YAML requer espaços)
• Faltam aspas em texto que contém caracteres especiais como :, # ou \
• Recuo deslocado em um espaço
• Um valor replace: que começa com { — deve ser colocado entre aspas: replace: "{{clipb}}"

Se falhas silenciosas de YAML são um problema recorrente para sua equipe, um editor de snippet baseado em GUI evita o problema completamente – você edita campos em um formulário em vez de validar o recuo a olho nu.

3. Espanso não funciona em um aplicativo específico

Alguns aplicativos – especialmente aplicativos Electron (VS Code, Slack, Discord), terminais e aplicativos com manipulação de entrada personalizada – não recebem as teclas simuladas de Espanso corretamente.

Correção no Linux: Certifique-se de estar usando o back-end de injeção correto. Edite ~/.config/espanso/config/default.yml:

backend: Auto

Tente alternar entre Auto, Clipboard e Inject:

backend: Clipboard

Correção no Windows: Execute o Espanso como administrador, especialmente para aplicativos executados com privilégios elevados.

Correção no macOS: Vá para Configurações do sistema → Privacidade e segurança → Acessibilidade, remova Espanso da lista e adicione-o novamente.

4. Permissões de acessibilidade ausentes (macOS)

Sem permissões de acessibilidade, Espanso não pode monitorar as teclas digitadas ou simular a saída de texto.

Correção:

1. Abra Configurações do sistema → Privacidade e segurança → Acessibilidade
2. Encontre Espanso na lista
3. Desligue e ligue novamente
4. Reinicie Espanso: espanso restart

Essa dança de redefinição de permissão é comum após cada versão pontual do macOS. Se preferir não repeti-la, veja como o Lightning Assist lida com as permissões do macOS (uma concessão única sobrevive às atualizações do sistema).

💡 Gastando mais tempo consertando o Espanso do que usando-o? Lightning Assist é um expansor de texto gráfico sem arquivos YAML, comandos de IA integrados e o mesmo suporte Linux. Experimente gratuitamente por 14 dias → — sem cartão de crédito.

5. Gatilho não dispara – Tipo de gatilho errado

Por padrão, Espanso usa gatilhos de palavras que só se expandem após um separador de palavras (espaço, nova linha, pontuação). Se você digitar o gatilho no meio de uma palavra, ele não se expandirá.

Correção: Verifique o tipo de gatilho no arquivo de correspondência. Use word: false se quiser acionar em qualquer lugar:

matches:
  - trigger: ":sig"
    replace: "Best regards,\nYour Name"
    word: false

Ou use o tipo de gatilho regex para ter mais controle:

matches:
  - regex: ":sig$"
    replace: "Best regards,\nYour Name"

6. Espanso não funciona após atualização do sistema

As atualizações do sistema operacional – especialmente em macOS e Linux – geralmente revogam permissões de acessibilidade ou quebram o serviço do sistema.

Correção:

1. Conceda novamente permissões de acessibilidade (consulte Correção 4 para macOS)
2. No Linux, registre novamente o serviço systemd: espanso service register
3. No Windows, verifique se o Espanso ainda está na lista de inicialização

7. Arquivo de configuração no local errado

Espanso procura arquivos de configuração em locais específicos. Colocar seus arquivos de correspondência .yml na pasta errada significa que eles nunca serão carregados.

Locais de configuração padrão:

• Linux: ~/.config/espanso/
• macOS: ~/Library/Application Support/espanso/
• Windows: %APPDATA%\espanso\

Os arquivos de correspondência devem estar no subdiretório match/. Execute espanso path para ver os caminhos exatos do seu sistema.

8. Espanso entra em conflito com outro aplicativo

Alguns aplicativos ou ferramentas de acessibilidade registram teclas de atalho globais que entram em conflito com o monitoramento de teclas do próprio Espanso.

Correção:

• Desative temporariamente outras ferramentas de acessibilidade, leitores de tela ou gerenciadores de teclas de atalho
• Verifique se há erros nos registros de Espanso: espanso log
• Tente executar espanso doctor para um diagnóstico completo

9. Espanso Não Inicia no Wayland

Em sessões Wayland (o padrão no Ubuntu, Fedora e em todos os desktops GNOME atuais), o Espanso precisa de sua versão dedicada para Wayland e de uma permissão única no binário; sem qualquer um desses, ele falha ao iniciar ou inicia e nunca expande (issue #2223).

Correção: Verifique seu tipo de sessão com echo $XDG_SESSION_TYPE. Se o resultado for wayland:

1. Instale o pacote específico para Wayland (espanso-debian-wayland-amd64.deb no Debian/Ubuntu, o RPM Terra no Fedora), não o de X11.
2. Conceda a capacidade que o Espanso precisa para ler /dev/input e escrever em /dev/uinput: sudo setcap "cap_dac_override+p" $(which espanso). Este é o passo do próprio guia de instalação do Espanso para Linux. As capacidades de arquivo são anexadas ao binário em si, então se a expansão parar após uma atualização do Espanso, execute este comando novamente.
3. Execute espanso service register e espanso start.

Certifique-se de estar usando o Espanso 2.4.0 ou superior (2.4.0 foi lançado em 21 de julho de 2026, 2.4.1 em 2 de setembro de 2026). A versão 2.4.0 adicionou detecção de aplicativos para compositores wlroots (Sway, Hyprland, labwc, Wayfire) e corrigiu uma falha de instalação na sessão Wayland do Fedora; a 2.4.1 adicionou o arquivo desktop e o ícone no Linux. Mesmo assim, o guia de instalação do Espanso ainda classifica o suporte a Wayland como "experimental": layouts de teclado não americanos devem ser configurados manualmente no arquivo de configuração, correspondências específicas de aplicativos funcionam apenas no KDE com kdotool instalado, o GNOME apresenta um pequeno flicker com o backend da área de transferência, e um teclado recém-conectado precisa de espanso restart.

Uma mudança em 2026: "basta fazer login em uma sessão X11" não é mais uma opção no GNOME. O GNOME 50 removeu completamente a sessão X11, então o Ubuntu 26.04 LTS — e qualquer outra distribuição com GNOME 50 — é exclusivamente Wayland (aplicativos X11 ainda rodam via XWayland, mas a versão X11 do Espanso não consegue ver as teclas de aplicativos nativos Wayland). Se a expansão no Wayland continuar instável, as opções restantes são um compositor que o Espanso suporte bem (KDE ou um compositor wlroots) ou um expansor de texto cujo suporte a Wayland não seja experimental — veja nosso guia de expansão de texto no Wayland.

Ainda não está funcionando? Verifique os registros

espanso log

Isso mostra exatamente por que o Espanso está falhando. Procure erros de permissão, erros de análise ou problemas de back-end.

Visão geral: Espanso x Lightning Assist

Recurso	Espanso	Lightning Assist
Código aberto	✅	❌ (comercial, teste de 14 dias)
Preços	Grátis / doações	Grátis (até 20 snippets, pastas e uma equipe); Pro US$ 5,99/mês. Recursos de IA medidos por meio de Créditos de IA (1000 por mês incluídos no Pro, comprados conforme a necessidade no plano gratuito).
Multiplataforma (Windows, macOS, Linux)	✅	✅
Configuração	Arquivos YAML	Editor gráfico
Comandos de IA (reescrever, aprimorar, etc.)	❌	✅ — créditos de IA, sem assinatura
Voz para texto push-to-talk	❌	✅ — também funciona no nível gratuito, consome créditos de Speech
Compartilhamento de snippets em equipe	❌ (soluções alternativas da comunidade)	✅ embutido
Experiência de depuração	CLI (espanso doctor, registros)	Painel de status da GUI

Ambos estão disponíveis para Windows, macOS e Linux. A escolha geralmente se resume a: você prefere CLI + arquivos de configuração + grátis (Espanso) ou GUI + IA + voz + pago (Lightning Assist).

Quando a configuração de Espanso se torna um fardo de manutenção

A configuração YAML de Espanso oferece poder, mas adiciona atrito real - especialmente ao começar, depurar falhas silenciosas ou colaborar com uma equipe que não se sente confortável com arquivos de configuração.

Se você está gastando mais tempo consertando Espanso do que realmente usando-o, considere Lightning Assist - um expansor de texto gráfico para Windows, Mac e Linux com uma GUI completa, comandos de IA integrados, digitação por voz push-to-talk e compartilhamento de snippets em equipe. Sem arquivos de configuração, sem YAML. Baixe o teste gratuito de 14 dias – não é necessário cartão de crédito.

Por padrão, seus trechos se expandem enquanto você digita — sem precisar de atalho de teclado: o modo padrão na tela Ativação do aplicativo é Inline. Digite a abreviação do seu trecho, como ;meeting, e ela é substituída enquanto você digita. Um símbolo inicial como ; mantém as abreviações distintas das palavras comuns. Inline tem dois estilos: Instantâneo dispara no momento em que a abreviação está completa, e Após espaço espera por um espaço. Prefere uma tecla deliberada? Mude para Atalho: digite a abreviação e depois aperte a sua tecla de atalho. Veja todos os modos de ativação →

Para uma comparação detalhada, consulte Lightning Assist vs Espanso.