SSD Nodes Learn Hosting plans →
Guides Matt ConnorPar Matt Connor

Corriger « unknown terminal type » via SSH

L’erreur « unknown terminal type » vient d’un nom TERM absent du serveur. Ajoutez l’entrée terminfo dans votre répertoire personnel, sans accès root.

Verified Every command ran end-to-end on a fresh Ubuntu 24.04 server, August 13, 2026.

Ce que signifie « unknown terminal type »

Une erreur « unknown terminal type » via SSH signifie que le nom indiqué dans TERM ne correspond à aucune entrée de la base de données terminfo sur le serveur. Votre émulateur définit ce nom sur votre ordinateur portable. La base de données qui doit le reconnaître se trouve sur la machine distante. Lorsque la recherche échoue, tous les programmes curses de ce serveur s’arrêtent avant d’afficher quoi que ce soit, car ils ne disposent d’aucune description des fonctionnalités de votre terminal.

Pour conserver toutes les fonctionnalités de votre émulateur, il suffit de compiler votre propre entrée terminfo dans ~/.terminfo sur le serveur. Dans une installation standard, comme celle de Debian, ncurses recherche votre répertoire personnel avant les répertoires système (seule une variable $TERMINFO définie est consultée auparavant). Cette opération ne nécessite donc pas root et ne modifie rien pour les autres utilisateurs. Cette recherche dans le répertoire personnel est facultative dans ncurses, d’où l’importance de la vérification après la correction.

TERM est un nom, terminfo est la base de données

TERM contient une chaîne unique, et cette chaîne est uniquement un nom. terminfo est une base de données compilée de descriptions de terminaux, et ce nom permet à un programme de trouver la bonne description. Une description indique le nombre de couleurs du terminal, les octets qui déplacent le curseur à la ligne 12, colonne 40, les octets envoyés par la touche F5 et la capacité à afficher un soulignement stylisé. ncurses, la bibliothèque sur laquelle reposent presque toutes les interfaces utilisateur en mode texte sous Linux, lit cette description au démarrage. Des programmes comme top, less, nano et watch ne peuvent pas afficher un seul écran sans elle.

Examinez votre propre entrée :

echo "$TERM"
tput longname
infocmp -1 | head -20

tput longname affiche la description lisible par un humain de ce que désigne TERM. Pour xterm-256color, la commande affiche :

xterm with 256 colors

infocmp -1 désassemble l’entrée et affiche une capacité par ligne. Elle omet les capacités étendues (définies par l’utilisateur), sauf si vous ajoutez -x, comme dans infocmp -1 -x. Si les deux commandes fonctionnent, la base de données de cette machine connaît ce terminal. C’est également l’état requis de l’autre côté d’une connexion SSH.

Pourquoi cela ne casse qu’avec SSH

SSH envoie le nom, et rien d’autre. Lorsque le client demande un pseudo-terminal, TERM est transmis avec cette demande. Le manuel d’OpenSSH est explicite : « la variable d’environnement TERM est toujours envoyée lorsqu’un pseudo-terminal est demandé, car le protocole l’exige ». Votre shell de connexion sur le VPS reçoit donc TERM=xterm-ghostty, xterm-kitty ou le nom utilisé par votre émulateur. La description associée à ce nom reste sur votre ordinateur portable, dans sa base de données. Un serveur construit avant l’apparition de votre émulateur n’a jamais rencontré ce nom. Rien dans la connexion SSH elle-même ne copie les descriptions de terminaux, et c’est volontaire : le protocole transporte un nom, pas une liste de capacités.

Reproduisez l’échec sur votre propre machine avec un nom qui n’existe certainement pas :

TERM=xterm-nosuchthing tput colors
echo "$?"
tput: unknown terminal "xterm-nosuchthing"

Le code de sortie est 3, que le manuel de tput décrit comme un « type de terminal non reconnu ». Chaque programme curses effectue la même recherche. Un nom manquant produit donc un message différent dans chaque programme, avec une seule cause commune. nano s’arrête avec Error opening terminal: xterm-nosuchthing., l’échec standard de ncurses lorsqu’il ne peut pas charger une description au démarrage. vim affiche E558: Terminal entry not found in terminfo. less affiche WARNING: terminal is not fully functional. Un pager qui fonctionne partiellement et un éditeur qui refuse de démarrer ressemblent à des bugs sans rapport. Ils sont dus au même fichier manquant.

Où ncurses recherche l’entrée

ncurses effectue ses recherches dans un ordre fixe, documenté dans terminfo(5) :

  1. $TERMINFO, s’il est défini. Il est vérifié en premier.
  2. $HOME/.terminfo. Le manuel le décrit comme « une fonctionnalité facultative qui peut être entièrement omise de la bibliothèque », ou qui peut être limitée afin que les programmes privilégiés ne l’utilisent pas par accident.
  3. Tous les répertoires indiqués dans $TERMINFO_DIRS.
  4. Les emplacements intégrés à la compilation, qui incluent /etc/terminfo, /lib/terminfo et /usr/share/terminfo sur Debian et Ubuntu.

Exécutez infocmp -D sur le serveur pour afficher la liste utilisée par sa propre version de ncurses, au lieu de vous fier aux chemins ci-dessus. L’étape 2 est l’élément déterminant. La version de ncurses fournie par Debian ne désactive pas cette fonctionnalité. Lorsqu’elle est disponible, votre répertoire personnel est recherché avant tout répertoire système. Un fichier placé dans ~/.terminfo suffit donc à corriger la recherche pour votre compte, sans installer de paquet et sans accès root. Exécuter tput longname après la correction permet de vérifier si la version installée sur votre serveur la prend en charge. La seule exception concerne l’étape 1 : si echo "$TERMINFO" affiche quelque chose sur le serveur, cet emplacement est vérifié en premier. Une entrée portant le même nom à cet endroit a priorité sur la vôtre.

Correctif 1 : utiliser un TERM déjà connu du serveur

Le moyen le plus rapide de débloquer la situation consiste à indiquer un autre terminal pour une connexion :

TERM=xterm-256color ssh user@203.0.113.10

Pour rendre ce réglage permanent pour cet hôte, ajoutez-le dans ~/.ssh/config sur votre ordinateur portable :

Host vps1
    HostName 203.0.113.10
    User deploy
    SetEnv TERM=xterm-256color

L’utilisation de SetEnv pour remplacer TERM nécessite OpenSSH 8.7 ou une version ultérieure sur le client, publiée en août 2021. Les clients plus anciens envoient systématiquement le TERM de votre émulateur, quelle que soit cette ligne. TERM est la seule variable qui ne nécessite pas l’autorisation du serveur : le manuel indique que « comme pour SendEnv, à l’exception de la variable TERM, le serveur doit être configuré pour accepter la variable d’environnement ». Cela fonctionne donc même avec un sshd renforcé qui ne contient aucune ligne AcceptEnv.

Contrepartie : tout ce que votre émulateur décrit au-delà de xterm-256color standard. Cela inclut les couleurs 24 bits annoncées par la capacité RGB et les soulignements stylés via Smulx. Les programmes qui s’appuient sur l’entrée terminfo ne peuvent plus détecter ces capacités. Ils utilisent donc 256 couleurs et un soulignement simple, sauf si vous les configurez pour envoyer malgré tout les séquences correspondantes. Vim peut par exemple continuer à afficher des couleurs 24 bits avec set termguicolors, car ses séquences t_8f et t_8b intégrées fonctionnent avec la plupart des terminaux. L’affichage fonctionne. Il est simplement moins riche que celui du terminal choisi.

Ne corrigez pas ce problème en ajoutant export TERM=xterm-256color dans votre .bashrc sur le serveur. Ce fichier est exécuté pour chaque connexion, y compris celles provenant d’un terminal dont le nom est connu du serveur. Il dégrade donc les sessions qui fonctionnaient déjà correctement. Conservez la surcharge sur le client, où vous savez quel émulateur vous utilisez.

Correctif 2 : envoyer votre entrée terminfo au serveur une seule fois

C’est le correctif qui conserve votre émulateur intact. Décompilez l’entrée localement, transmettez-la via SSH, puis compilez-la sur le serveur distant :

infocmp -x | ssh user@203.0.113.10 -- tic -x -

infocmp -x affiche l’entrée correspondant à votre TERM actuel sous forme de texte source, y compris les capabilities étendues (définies par l’utilisateur). tic -x recompile cette source en description binaire sur le serveur. Le -x des deux côtés est important : sans lui, les capabilities telles que Smulx sont supprimées pendant le transfert et vous installez une copie dégradée de votre propre terminal.

tic écrit dans le répertoire système lorsque c’est possible, puis utilise $HOME/.terminfo si l’utilisateur n’a pas les droits d’écriture à cet emplacement. Un compte standard sur un VPS utilise son répertoire personnel, ce qui est le comportement recherché. Vous pouvez également indiquer la destination :

infocmp -x | ssh user@203.0.113.10 -- tic -x -o '~/.terminfo' /dev/stdin

Les guillemets autour de ~/.terminfo ne sont pas décoratifs. ssh regroupe les mots de la commande en une seule chaîne et la transmet au shell distant. Sans guillemets, ~ est d’abord développé par votre shell local. Vous envoyez alors un /home/yourname/.terminfo littéral à une machine où votre compte peut porter un autre nom. tic échoue avec une erreur de permissions ou écrit dans un chemin que ncurses ne recherche jamais. Entourez le tilde de guillemets afin que le shell distant le développe.

Connectez-vous et vérifiez :

ssh user@203.0.113.10
tput longname
ls -R ~/.terminfo

tput longname affiche la description de votre terminal, ce qui signifie que la recherche aboutit désormais. ls affiche le fichier compilé dans un sous-répertoire portant le nom de la première lettre du terminal. Exécutez ensuite top ou surveillez uptime avec watch -n1, qui réaffiche le résultat via la même bibliothèque, afin de vérifier qu’un véritable programme curses affiche correctement l’écran.

Le coût : une étape par serveur, et l’entrée reste dans le répertoire personnel d’un seul compte sur une seule machine. Si vous reconstruisez le VPS, elle disparaît. Ajoutez la commande à l’outil que vous utilisez pour provisionner et gérer plusieurs serveurs simultanément, afin qu’un nouvel hôte dispose déjà de l’entrée compilée.

Correctif 3 : installer la base terminfo étendue

Si vous avez les droits root et voulez que le nom soit résolu pour tous les comptes de la machine :

sudo apt update
sudo apt install ncurses-term
tput -T xterm-ghostty longname

ncurses-term contient les descriptions de terminaux absentes de l’installation de base. Il corrige le problème pour root et pour tous les autres utilisateurs, contrairement au correctif 2.

Cela fonctionne uniquement si l’entrée de votre terminal existe dans la version de ncurses fournie par votre distribution. Vérifiez donc sa présence au lieu de partir du principe qu’elle existe. Ubuntu 24.04 fournit ncurses-bin 6.4+20240113-1ubuntu2.2 (en novembre 2026). L’entrée de Ghostty a été ajoutée en amont dans ncurses 6.5-20241228, qui est plus récente. Par conséquent, apt install ncurses-term sur Ubuntu 24.04 ne peut pas générer d’entrée xterm-ghostty, même si vous l’exécutez plusieurs fois. tput -T <name> longname effectue la vérification : il affiche la description lorsque l’entrée est présente, et unknown terminal avec le code de sortie 3 lorsqu’elle est absente.

Pour installer une seule entrée à l’échelle du système au lieu du paquet complet, copiez la source, puis compilez-la en tant que root :

infocmp -x | ssh user@203.0.113.10 -- 'cat > /tmp/term.src'
ssh -t user@203.0.113.10 -- sudo tic -x -o /usr/share/terminfo /tmp/term.src

Le -t de la deuxième commande alloue un pseudo-terminal afin que sudo puisse demander le mot de passe. Sans cette option, ssh n’alloue aucun terminal pour une commande distante, et sudo s’arrête avec sudo: a terminal is required to read the password; either use the -S option to read from standard input or configure an askpass helper lorsqu’un mot de passe est requis. Cette erreur concerne l’absence de tty, et non terminfo.

Laissez l’émulateur effectuer le transfert

Certains émulateurs fournissent un utilitaire qui applique automatiquement le correctif 2. kitty propose un ssh kitten : kitten ssh myserver se connecte et copie automatiquement le terminfo de kitty sur l’hôte distant. Sa documentation indique aussi la forme manuelle, infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin, avec le tilde échappé pour la raison décrite plus haut. Ghostty documente infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x - et, depuis la version 1.2.0, fournit des fonctions d’intégration au shell activables (ssh-env et ssh-terminfo) qui automatisent les deux correctifs. Ghostty 1.4.0, publiée le 27 octobre 2026, ajoute un wrapper ghostty +ssh absent des versions 1.3.x, et les deux fonctions activables l’utilisent désormais. Il installe le terminfo fourni avec Ghostty sur l’hôte distant avant la connexion et utilise TERM=xterm-256color si cette installation échoue, par exemple lorsque le serveur ne possède pas de tic. Dans la version 1.4, ssh-env ne remplace plus non plus les lignes SetEnv dans ~/.ssh/config ; la configuration par hôte du correctif 1 est donc respectée.

Ces utilitaires exécutent les mêmes commandes que celles que vous venez de lancer manuellement. Il reste important de connaître la forme manuelle, car l’utilitaire ne peut pas intervenir lorsque la connexion est établie ailleurs, depuis un jump host ou dans un script.

Quand l’erreur revient

Sous sudo -i. Un shell de connexion en tant que root a HOME=/root, et sudo conserve votre TERM. ncurses recherche alors /root/.terminfo, qui ne contient pas votre entrée. L’échec revient donc uniquement pour root. Vérifiez-le avec sudo -i env, puis lisez les lignes HOME et TERM. Installez l’entrée dans le répertoire système. Une copie dans /root/.terminfo peut également fonctionner, mais ncurses peut limiter la recherche dans le répertoire personnel pour les processus privilégiés. Exécutez donc tput longname en tant que root pour le confirmer.

Dans tmux ou screen. Ces outils définissent leur propre TERM pour les programmes qui s’exécutent à l’intérieur. Il s’agit généralement de screen-256color ou de tmux-256color. Un serveur ancien connaît screen-256color et peut ne pas connaître tmux-256color. Le shell externe fonctionne alors correctement, tandis que tout échoue à l’intérieur de la session. La cause est la même, mais le nom est différent. Exécutez tput -T tmux-256color longname sur le serveur pour voir lequel des deux il connaît. Un atelier de terminal basé sur tmux masque ce problème jusqu’au jour où vous vous connectez à un hôte que vous n’avez pas encore corrigé.

Sur un serveur neuf. ~/.terminfo est propre à chaque compte et à chaque machine. Un VPS reconstruit est donc de nouveau vide.

L’écran s’affiche, mais les touches se comportent mal. Si l’affichage est correct, mais que les touches Home, End ou les touches de fonction insèrent des caractères inattendus, le nom a été résolu vers une entrée qui ne correspond pas à votre terminal. Les séquences de touches proviennent de la même entrée terminfo que les capacités d’affichage. Une entrée approximative produit donc des séquences de touches approximatives. C’est le résultat habituel de la correction 1 avec un émulateur dont les séquences de touches diffèrent de xterm. La correction 2 est la solution la plus propre, car l’entrée réelle de votre émulateur contient les bonnes séquences pour tous les programmes à la fois. Ce n’est pas la seule possibilité : la documentation de Vim indique que vous pouvez « modifier le code de touche avec la commande :set », et Vim demande directement ses codes de touche à un xterm récent au démarrage au lieu de dépendre uniquement de l’entrée.

FAQ

Pourquoi est-ce que je vois seulement « unknown terminal type » avec SSH ?

Parce que la base de données qui doit contenir l’entrée de votre terminal se trouve sur le serveur. Votre émulateur installe sa description sur la machine où il s’exécute. Les programmes locaux la trouvent donc sans intervention de votre part. SSH envoie uniquement la valeur de TERM, car le protocole transmet ce nom avec la demande de pseudo-terminal. ncurses sur la machine distante recherche ce nom dans la base distante, ne trouve rien, puis initscr échoue et le programme s’arrête.

Puis-je corriger ce problème sans accès root sur le serveur ?

Oui, dans une installation standard comme celle de Debian. ncurses recherche $HOME/.terminfo avant tout répertoire système. Seule une variable $TERMINFO définie sur le serveur est consultée avant ce chemin. Dans le cas normal, une entrée à cet emplacement suffit donc pour votre compte. La recherche dans le répertoire personnel est facultative dans ncurses. C’est pourquoi le contrôle tput longname ci-dessous est important. Exécutez infocmp -x | ssh user@host -- tic -x - une fois par serveur. tic écrit dans votre répertoire personnel lorsqu’il ne peut pas écrire dans le chemin système, ce qui est le cas normal pour un compte sans privilèges. Connectez-vous, puis exécutez tput longname pour vérifier que la recherche aboutit maintenant.

Que perdez-vous en définissant TERM=xterm-256color pour un hôte ?

Toutes les capacités décrites par votre émulateur au-delà de l’entrée xterm-256color, comme les couleurs 24 bits via RGB et les soulignements stylés via Smulx. Les programmes qui s’appuient sur l’entrée terminfo ne peuvent pas voir ces capacités. Ils utilisent donc la solution de repli la plus proche, sauf si vous les configurez autrement, comme le fait l’option termguicolors de Vim pour la couleur. Les séquences des touches de fonction peuvent également différer de celles de votre terminal réel. Placez ce réglage sur le client dans ~/.ssh/config plutôt que dans un .bashrc sur le serveur. Sinon, vous dégraderiez les sessions provenant de terminaux qui fonctionnaient déjà.

Pourquoi l’erreur réapparaît-elle après sudo -i ?

sudo -i démarre un shell de connexion en tant que root avec HOME=/root, tout en conservant la valeur de TERM. ncurses recherche alors /root/.terminfo au lieu de votre propre répertoire personnel et ne trouve rien. root rencontre donc le même échec que votre compte ne rencontre plus. Exécutez sudo -i env et vérifiez les lignes HOME et TERM. Compilez l’entrée dans le répertoire système avec sudo tic -x -o /usr/share/terminfo. Une copie dans /root/.terminfo peut également fonctionner, mais ncurses peut limiter la recherche dans le répertoire personnel pour les processus privilégiés. Vérifiez donc avec tput longname en tant que root.

Est-ce que apt install ncurses-term corrige toujours le problème ?

Non. Cette commande ajoute uniquement les entrées présentes dans la version de ncurses fournie par votre distribution. Ubuntu 24.04 fournit ncurses 6.4 (ncurses-bin 6.4+20240113-1ubuntu2.2, en novembre 2026), tandis que l’entrée de Ghostty a été ajoutée en amont dans ncurses 6.5-20241228. Ce paquet ne peut donc pas la contenir. Vérifiez avec tput -T <name> longname avant de vous fier au paquet. Installez vous-même l’entrée si le contrôle indique toujours un terminal inconnu.

Cet article vous a-t-il été utile ?

#terminfo#ssh#ncurses#tput#terminal