SSD Nodes Learn Hosting plans →
ガイド Matt Connor著者 Matt Connor

SSHの「unknown terminal type」を直す方法

SSHで「unknown terminal type」が出る原因と対処法を解説します。リモート側のterminfo不足を、root権限なしでホームディレクトリに登録して解決できます。

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

「unknown terminal type」の意味

SSH 経由で「unknown terminal type」エラーが発生する場合、TERM に設定された名前に一致するエントリが、サーバー上の terminfo データベースにありません。端末エミュレーターがその名前をラップトップ上で設定します。認識する必要があるデータベースは、リモートマシン上にあります。検索に失敗すると、そのサーバー上のすべての curses プログラムは、画面に何も描画する前に停止します。使用している端末の機能を示す記述がないためです。

端末エミュレーターの機能をすべて維持するには、サーバー上の ~/.terminfo に独自の terminfo エントリをコンパイルします。Debian の標準的なビルドでは、ncurses はシステムディレクトリより先にホームディレクトリを検索します($TERMINFO 変数が設定されている場合のみ、先にその変数が参照されます)。そのため root は不要で、他のユーザーには何も影響しません。ncurses では、このホームディレクトリの検索は任意です。そのため、修正後の確認が重要です。

TERM は名前であり、terminfo はデータベースです

TERM が保持する文字列は 1 つだけで、その文字列はキーにすぎません。terminfo は端末定義をコンパイルしたデータベースであり、プログラムはそのキーを使って適切な定義を検索します。定義には、端末が扱える色数、カーソルを 12 行 40 列へ移動するバイト列、F5 キーが送信するバイト列、装飾付き下線の描画可否などが記録されています。Linux のほぼすべてのテキストユーザーインターフェイスが基盤としているライブラリ ncurses は、起動時にこの定義を読み込みます。top、less、nano、watch などのプログラムは、この定義なしでは画面を 1 つも描画できません。

自分のエントリを確認します。

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

tput longname は、TERM が示す対象の人間が読みやすい定義を出力します。xterm-256color の場合は、次のように出力されます。

xterm with 256 colors

infocmp -1 はエントリを逆コンパイルし、機能を 1 行ずつ出力します。拡張機能(ユーザー定義機能)は、-x を追加しない限り省略されます。infocmp -1 -x のように指定します。両方のコマンドが機能する場合、このマシンのデータベースにはこの端末の定義があります。SSH 接続先でも、同じ状態が必要です。

SSH 経由でだけ動作しなくなる理由

SSH は名前だけを送信し、それ以外は送信しません。クライアントが擬似端末を要求すると、その要求とともに TERM が送信されます。OpenSSH のマニュアルには、「擬似端末が要求されるたびに、TERM 環境変数は必ず送信される。これはプロトコル上必要だからである」と明記されています。そのため、VPS 上のログインシェルには、TERM=xterm-ghostty、xterm-kitty、または使用しているターミナルエミュレーターの名前が渡されます。その名前に対応する定義は、ノートパソコン上のデータベースに残っています。ターミナルエミュレーターが存在する前に構築されたサーバーは、その名前を認識したことがありません。SSH 接続自体がターミナル定義をコピーすることはありません。これは意図的な仕様です。プロトコルが運ぶのは名前であり、機能の一覧ではないためです。

確実に存在しない名前を使って、自分のマシンでこの失敗を再現できます。

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

終了ステータスは 3 です。tput のマニュアルでは、これを「認識されないターミナルタイプ」と説明しています。すべての curses プログラムが同じ検索処理を実行するため、名前が 1 つ欠けているだけで、各プログラムから異なるメッセージが表示されます。しかし、原因はすべて同じです。nano は Error opening terminal: xterm-nosuchthing. で停止します。これは、起動時に定義を読み込めない場合の標準的な ncurses の失敗です。vim は E558: Terminal entry not found in terminfo を表示します。less は WARNING: terminal is not fully functional を表示します。一部だけ動作するページャーと、起動を拒否するエディターは、無関係なバグのように見えます。実際には、同じファイルが欠けています。

ncurses がエントリを検索する場所

ncurses は固定された順序で検索します。この順序は terminfo(5) に記載されています。

  1. $TERMINFO。設定されている場合に使用され、最初に確認されます。
  2. $HOME/.terminfo。マニュアルでは「ライブラリから完全に省略できるオプション機能」と説明されています。また、特権プログラムが誤って使用しないように制限される場合もあります。
  3. $TERMINFO_DIRS に列挙されたすべてのディレクトリ。
  4. コンパイル時に組み込まれた場所。Debian と Ubuntu では、/etc/terminfo、/lib/terminfo、/usr/share/terminfo などが含まれます。

サーバー上で infocmp -D を実行すると、上記のパスをそのまま信頼するのではなく、そのサーバーの ncurses ビルドが使用する検索先の一覧を表示できます。重要なのは手順 2 です。Debian の ncurses ビルドではこの機能が無効化されていません。機能が利用できる場合、システムディレクトリより先にホームディレクトリが検索されます。そのため、~/.terminfo の下にファイルを 1 つ置くだけで、そのアカウントの検索を修正できます。パッケージのインストールも root も必要ありません。修正後に tput longname を実行すると、サーバーのビルドがこの機能を使用するか確認できます。例外は手順 1 です。サーバー上で echo "$TERMINFO" が何かを出力する場合、その場所が最初に確認されます。そこに同じ名前のエントリがあると、こちらのエントリより優先されます。

修正 1: サーバーが認識している TERM を使用する

最も早く復旧するには、1 回の接続で別の端末を指定します。

TERM=xterm-256color ssh user@203.0.113.10

ノート PC の ~/.ssh/config に設定し、そのホストに対して永続化します。

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

SetEnv で TERM を上書きするには、クライアント側で OpenSSH 8.7 以降が必要です。OpenSSH 8.7 は August 2021 にリリースされました。古いクライアントでは、この行に関係なく、端末エミュレーター固有の TERM が送信されます。TERM は、サーバーの許可を必要としない唯一の変数です。マニュアルにも「SendEnv と同様ですが、TERM 変数を除き、サーバーは環境変数を受け入れる準備が必要です」と記載されています。そのため、AcceptEnv 行がまったくない、強化された sshd に対しても機能します。

代償は、単純な xterm-256color を超えて端末エミュレーターが表現する機能をすべて失うことです。これには、RGB capability で通知される 24-bit カラーや、Smulx による装飾下線が含まれます。terminfo エントリに依存するプログラムは、これらの機能を認識できなくなるため、明示的にシーケンスを送信するよう設定しない限り、256 色と通常の下線にフォールバックします。たとえば Vim は、set termguicolors を使用すれば 24-bit カラーを描画できます。組み込みの t_8f と t_8b のシーケンスが、ほとんどの端末で機能するためです。画面は表示されます。ただし、選択した端末より機能が少なくなります。

サーバーの .bashrc に export TERM=xterm-256color を追加して解決しないでください。そのファイルは、サーバーが認識している端末名からの接続を含め、すべての接続で実行されます。そのため、すでに正常なセッションまで機能を低下させます。使用している端末エミュレーターが分かるクライアント側で上書きしてください。

修正 2: terminfo エントリをサーバーへ一度送信する

この方法なら、エミュレーターを変更せずに済みます。ローカルでエントリを逆コンパイルし、SSH 経由で送り、接続先でコンパイルします。

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

infocmp -xは、現在のTERMのエントリを、拡張(ユーザー定義)機能を含むソーステキストとして出力します。tic -xは、そのソースをサーバー上でバイナリ形式の定義に戻します。両側で-xを指定することが重要です。これを指定しないと、Smulxなどの機能が転送中に失われ、自分の端末の機能を落としたコピーを送ることになります。

ticは、可能であればシステムディレクトリに書き込み、そこへの書き込み権限がない場合は$HOME/.terminfoにフォールバックします。VPS の一般ユーザーではホームディレクトリが使用されるため、これで問題ありません。保存先を指定することもできます。

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

~/.terminfoを囲む引用符は、単なる装飾ではありません。sshはコマンドの各語を 1 つの文字列に結合し、それをリモートシェルに渡します。そのため、~を引用符で囲まないと、最初にローカルシェルで展開されます。その結果、アカウント名が異なる可能性のあるマシンへ、文字どおりの/home/yourname/.terminfoを送ることになります。ticは権限エラーで失敗するか、ncurses が検索しないパスへ書き込みます。チルダを引用符で囲むと、リモートシェルが展開します。

ログインして確認します。

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

tput longnameが端末の定義を出力すれば、検索に成功しています。lsでは、端末名の先頭文字を名前とするサブディレクトリ内に、コンパイル済みファイルがあることを確認できます。次にtopを実行します。または、同じライブラリを使って画面を再描画するwatch -n1 uptimeを実行し、実際の curses プログラムが画面を描画できることを確認します。

必要な作業は、サーバーごとに 1 回実行することです。エントリは、1 台のマシンにある 1 つのアカウントのホームディレクトリに保存されます。VPS を再構築すると失われます。複数のサーバーを一度にプロビジョニングおよび管理するために使用している仕組みにこのコマンドを組み込み、新しいホストにエントリがコンパイル済みの状態で追加されるようにします。

Fix 3: 拡張 terminfo データベースをインストールする

root を使用でき、サーバー上のすべてのアカウントで名前を解決できるようにする場合は、次の手順を実行します。

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

ncurses-term には、基本インストールでは省かれる端末の説明が含まれています。これにより root と他のすべてのユーザーで名前を解決できますが、fix 2 では解決できません。

ただし、端末のエントリがディストリビューションに含まれる ncurses のリリースに存在する場合に限り有効です。思い込まずに確認してください。Ubuntu 24.04 には、2026 年 11 月時点で ncurses-bin 6.4+20240113-1ubuntu2.2 が含まれています。Ghostty のエントリは upstream の ncurses 6.5-20241228 で追加されました。これはより新しいバージョンであるため、Ubuntu 24.04 の apt install ncurses-term を何度実行しても xterm-ghostty エントリは生成できません。tput -T <name> longname で確認できます。エントリが存在する場合は説明を出力し、存在しない場合は終了ステータス 3 で unknown terminal になります。

パッケージ全体ではなく、単一のエントリをシステム全体にインストールするには、ソースを転送して 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

2 番目のコマンドにある -t は pseudo terminal を割り当てます。そのため、sudo はパスワードを要求できます。これがない場合、ssh はリモートコマンド用の端末を割り当てません。パスワードが必要になると sudo は sudo: a terminal is required to read the password; either use the -S option to read from standard input or configure an askpass helper で停止します。このエラーの原因は tty がないことであり、terminfo ではありません。

エミュレーターに転送させる

一部のエミュレーターには、fix 2 を自動的に実行するヘルパーが付属しています。kitty には ssh kitten があり、kitten ssh myserver によって接続時に kitty の terminfo をリモートホストへ自動的にコピーします。ドキュメントには、上記の理由によりチルダをエスケープした手動形式 infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin も記載されています。Ghostty では infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x - を案内しています。また、version 1.2.0 以降では、両方の fix を自動化する opt-in の shell integration 機能(ssh-env と ssh-terminfo)が付属しています。2026 年 10 月 27 日にリリースされた Ghostty 1.4.0 では、1.3.x releases にはない ghostty +ssh wrapper が追加され、現在はこの 2 つの opt-in 機能からそれが呼び出されます。接続前に Ghostty に同梱された terminfo をリモートホストへインストールし、インストールに失敗した場合は TERM=xterm-256color にフォールバックします。たとえば、サーバーに tic がない場合です。1.4 では、ssh-env が ~/.ssh/config 内の SetEnv lines を上書きしなくなったため、fix 1 のホスト単位の上書きが尊重されます。

これらのヘルパーは、直前に手動で実行したものと同じコマンドを実行します。それでも手動形式を把握しておくことは重要です。接続の開始場所が別の場合、たとえば jump host 上やスクリプト内の場合、ヘルパーは動作できないためです。

エラーが再発する場合

sudo -i の場合。 root のログインシェルでは HOME=/root になっており、sudo が TERM を維持しています。ncurses は現在 /root/.terminfo を検索しますが、そこには root 用のエントリがないため、root の場合だけ障害が再発します。sudo -i env で確認し、HOME と TERM の行を読み取ります。そのエントリをシステムディレクトリにインストールします。/root/.terminfo にコピーしても機能する場合がありますが、ncurses は特権プロセスに対するホームディレクトリの検索を制限することがあります。そのため、root として tput longname を実行して確認します。

tmux または screen 内の場合。 これらは内部で実行されるプログラム向けに独自の TERM を設定します。通常は screen-256color または tmux-256color です。古いサーバーは screen-256color を認識していても、tmux-256color を認識しないことがあります。その場合、外側のシェルは正常でも、セッション内のすべてで障害が発生します。原因は同じで、名前だけが異なります。サーバー上で tput -T tmux-256color longname を実行すると、2 つのうちどちらを保持しているか確認できます。tmux を中心に構成されたターミナル作業環境を使うと、まだ修正していないホストに接続する日まで、この問題に気付きにくくなります。

新しいサーバーの場合。 ~/.terminfo はアカウントごと、マシンごとに存在するため、再構築した VPS は再び空の状態で始まります。

画面は描画されるが、キーが正しく動作しない場合。 表示は正常でも、Home、End、ファンクションキーを押すと余計な文字が入力される場合、解決された名前が端末に合わないエントリを指しています。キーシーケンスは描画機能と同じ terminfo エントリから取得されるため、近似的なエントリではキーも正しく動作しません。これは、キーシーケンスが xterm と異なるエミュレーターで修正 1 を行った場合に、通常発生する結果です。修正 2 が最も確実な方法です。使用しているエミュレーターの実際のエントリに、すべてのプログラムで正しいシーケンスが含まれるためです。ただし、これだけが方法ではありません。Vim のドキュメントには「:set コマンドでキーコードを変更できる」と記載されています。また Vim は、エントリだけに依存せず、起動時に新しい xterm へキーコードを直接問い合わせます。

FAQ

SSH 経由で "unknown terminal type" としか表示されないのはなぜですか?

端末のエントリを保持するデータベースは、サーバー側にある必要があるためです。端末エミュレーターは、実行されているマシンに端末の説明をインストールするため、ローカルのプログラムは特別な操作なしでそれを見つけられます。SSH が送信するのは TERM の値だけです。プロトコルでは、その名前を pseudo-terminal の要求とともに渡すためです。リモート側の ncurses はリモートのデータベースでその名前を検索しますが、見つかりません。そのため initscr に失敗し、プログラムが停止します。

サーバーで root でなくても修正できますか?

はい。Debian の標準的なビルドなどでは可能です。ncurses は、システムディレクトリより先に $HOME/.terminfo を検索します。サーバー側で $TERMINFO 変数が設定されている場合だけ、それが先に確認されます。そのため通常は、アカウントのホームディレクトリにエントリを置くだけで十分です。ncurses ではホームディレクトリの検索がオプション扱いなので、以下の tput longname の確認が重要になります。サーバーごとに 1 回、infocmp -x | ssh user@host -- tic -x - を実行します。システムパスに書き込めない場合、tic はホームディレクトリに書き込みます。権限のないアカウントでは、これが通常の動作です。ログインして tput longname を実行し、検索によって解決できるようになったことを確認します。

ホストに TERM=xterm-256color を設定すると、何が失われますか?

xterm-256color エントリ以外に端末エミュレーターが示すすべての機能が失われます。たとえば、RGB による 24-bit カラーや、Smulx による装飾付き下線などです。terminfo エントリに依存するプログラムは、それらの機能を認識できません。そのため、別途設定しない限り最も近い代替機能を使用します。カラーについて Vim の termguicolors オプションが行う処理がその例です。ファンクションキーのシーケンスも、実際の端末とは異なる場合があります。すでに正常に動作している端末からのセッションまで低機能化しないように、設定はサーバーの .bashrc ではなく、クライアント側の ~/.ssh/config に記述してください。

sudo -i の後にエラーが再発するのはなぜですか?

sudo -i は HOME=/root を使って root として login shell を起動しますが、TERM の値は保持します。すると ncurses は自分のホームディレクトリではなく /root/.terminfo を検索し、何も見つけられません。そのため root では、通常のアカウントでは発生しなくなった同じエラーが発生します。sudo -i env を実行し、HOME と TERM の行を確認してください。sudo tic -x -o /usr/share/terminfo を使ってエントリをシステムディレクトリにコンパイルします。/root/.terminfo にコピーしても動作する場合があります。ただし ncurses は特権プロセスに対するホームディレクトリの検索を制限することがあるため、root として tput longname を実行して確認してください。

apt install ncurses-term で必ず修正できますか?

いいえ。ディストリビューションがパッケージ化した ncurses のリリースに存在するエントリだけが追加されます。Ubuntu 24.04 は ncurses 6.4(2026 年 11 月時点では ncurses-bin 6.4+20240113-1ubuntu2.2)を提供します。Ghostty のエントリは ncurses 6.5-20241228 で上流に追加されたため、そのパッケージには含まれていません。パッケージに依存する前に tput -T <name> longname で確認してください。それでも unknown terminal と表示される場合は、エントリを自分で配置します。

この記事は役に立ちましたか?

#terminfo#ssh#ncurses#tput#terminal