安裝
影片
指南
Terminux 0.1.0 安裝指南
目錄
- 平台支援
- 前置條件
- 找出你的 Qt root
- 快速路徑
- 搭配影片閱讀
- S01-intro — 本課範圍
- S02-prereqs — 備妥執行環境並找出 Qt root
- S03-identify — 確認安裝包身分
- S04-extract — 解開安裝包
- S05-install — 以使用者身分安裝 Terminux
- S06-check — 檢查安裝版本與 Qt 配對
- S07-launch — 啟動 Terminux 並選擇介面語言
- S08-verify — 驗證 Terminux 內建終端機
- 故障處理速查
- 附錄 A — 選用:較短的啟動命令(PATH)
- 附錄 B — Shell 整合與工具 wrapper
- 附錄 C — tcsh/csh 使用者
- 附錄 D — EDA 工具、流程與 DQE
- 附錄 E — AI/LLM provider
- 附錄 F — 移除(僅供參考,本課未執行)
- 附錄 G — 平台與操作限制
適用對象。 第一次在自己的 Linux 帳號安裝 Terminux 0.1.0 可攜式安裝包的工程師,例如 IC 設計或 CAD 工程師。
完成後你會得到。 Terminux 以一般使用者身分安裝在家目錄(不需要 sudo)、與 Qt 的配對通過檢查、Terminux 視窗以英文介面開啟,且內建終端機能執行普通 shell 指令。
本 Guide 不證明的事。 不驗證 EDA 工具、工具 wrapper、DQE 資料、AI/LLM provider 或任何 signoff 流程。S08 的 echo 成功,只代表內建終端機可以使用。
兩種終端機。 系統終端機 是桌面環境原本的終端機程式,執行 Bash;Terminux 內建終端機 是 Terminux 視窗裡的終端機區域。每一步都會註明要在哪一個操作。
平台支援
| 平台 | 本版本 狀態 |
|---|---|
| Ubuntu 24.04 x86_64、Bash、X11(Xorg)桌面工作階段 | 已實測:Ubuntu 24.04.5、glibc 2.39、Xorg/XFCE 桌面 |
| RHEL/Rocky/AlmaLinux 9、CentOS Stream 9(x86_64) | 安裝說明列為支援,但 本版本 未實測 |
| 其他 Linux 發行版、原生 Wayland、遠端顯示 | 未驗證 |
| macOS、Windows、非 x86_64 CPU | 本安裝包不支援;非 x86_64 系統會被安裝程式擋下 |
最低 CPU、記憶體與安裝耗時 尚未量測。實錄使用 4 vCPU/8 GiB 的虛擬機,這不是最低需求。
前置條件
基本安裝只需要下表項目。標示「系統管理員」的項目,請洽系統管理員或 CAD/IT 團隊。
| 條件 | 說明 | 通常由誰提供 |
|---|---|---|
| Ubuntu 24.04 x86_64 | glibc 2.34 以上,且系統 libstdc++ 提供 GLIBCXX_3.4.29。安裝程式會檢查兩者,缺一即停止。 |
系統 |
| 一般使用者帳號 | 可寫的家目錄與足夠空間;安裝與啟動使用同一帳號。不需要也不建議使用 sudo。 |
你 |
| 系統終端機使用 Bash | 步驟使用 echo $?、read 等 Bash 語法。 |
系統 |
| 基本工具 | tar、gzip、sha256sum、ls、grep、readlink(Ubuntu 桌面預設即有)。 |
系統 |
| 外部 Qt 6.7.3 | 安裝包不含 Qt。 需要 Qt 6 Desktop gcc 64-bit 安裝,含函式庫、QML 模組,以及 xcb 與 offscreen 平台 plugin。安裝程式原始碼接受 Qt 6.x 且 ≥ 6.7.0,但只實測過 6.7.3。 |
系統管理員 |
| X11/xcb、OpenGL/EGL 與 GSSAPI 系統函式庫 | 見下方套件範例。 | 系統管理員 |
| 圖形登入工作階段 | 在執行 Terminux 的那台主機上,以同一使用者登入的實際桌面工作階段。 | 你/系統管理員 |
| 字型 | 能顯示所需文字的字型;實錄使用 Noto 字型(含 CJK)。 | 系統管理員 |
| 磁碟空間 | 安裝程式會自行計算需求;空間不足時停止,並顯示需要與可用的 bytes。 | 你 |
已隨包提供,不需另外安裝: Python 3.12(實測安裝包為 3.12.14)與基本 Python 相依套件,安裝時從安裝包離線安裝。不需要 pip、uv、編譯器或 CMake。
基本安裝不需要: EDA 工具、工具 wrapper、tcsh 設定、AI/LLM provider 或 API key、project ID。請見附錄。
X11/xcb、OpenGL/EGL 與 GSSAPI 的 Ubuntu 24.04 套件範例。 來自安裝說明與實錄環境設定,只是範例,不是已證明的最小清單;若有缺漏,安裝程式與 Qt 檢查器會列出確切的函式庫檔名(SONAME)。
| 用途 | Ubuntu 24.04 套件範例 |
|---|---|
| xcb cursor | libxcb-cursor0 |
| xcb utility、ICCCM、image、keysyms、render-util | libxcb-util1、libxcb-icccm4、libxcb-image0、libxcb-keysyms1、libxcb-render-util0 |
| XKB、X11、xcb | libxkbcommon0、libxkbcommon-x11-0、libx11-6、libx11-xcb1、libxcb1 |
| OpenGL/EGL | libegl1、libgl1、libglx0、libopengl0 |
| GSSAPI | libgssapi-krb5-2 |
找出你的 Qt root
Terminux 需要你的 Qt root 路徑:直接包含 lib/、qml/、plugins/(以及 lib/cmake/Qt6/)的那個資料夾。
- 以 Qt SDK 的桌面版安裝而言,通常是版本資料夾底下的編譯器資料夾,例如結尾為
/6.7.3/gcc_64的路徑(此形式依安裝說明)。 - 它 不是 裡面的
bin/資料夾,也 不是 只含版本或編譯器資料夾的上層資料夾。 - 系統管理員可能把 Qt 裝在任何位置;不確定時請直接詢問確切路徑。
- 錄影機器的 Qt root 是
/opt/qt673。這個路徑只屬於那台機器,不是預設值,你的機器上可能不存在。
S02 會示範在安裝前如何記下並檢查你的 Qt root。
快速路徑
已熟悉背景的讀者,可依下列七步完成本課:
- S02 — 把 Qt root 存進
QT_ROOT,並檢查結構與版本。 - S03 — 驗證安裝包 checksum。沒有可信參考時 STOP。
- S04 — 解開安裝包並進入
terminux-0.1.0。 - S05 — 以
--qt-dir "$QT_ROOT" --yes執行安裝程式;echo $?必須印出0。 - S06 —
readlink印出0.1.0;Qt 檢查通過;echo $?印出0。 - S07 — 啟動
~/.local/bin/terminux。若介面是中文:Language → English,關閉視窗後再啟動一次。 - S08 — 在 Terminux 內建終端機執行
echo hello-terminux,看到hello-terminux單獨成一行。
搭配影片閱讀
影片與本指南依 S01–S08 分節。安裝前請依 S03 驗證安裝包。
S01-intro — 本課範圍
影片:R1.1 S01-intro 0:00.0–0:12.2
目的
開始前先了解成果與限制:以預編譯安裝包完成使用者層安裝、檢查 Qt、首次啟動,並在 Terminux 內建終端機執行一個普通指令。
開始前確認
先閱讀上方的「平台支援」與「前置條件」。若系統與實測平台不同,步驟或許仍可運作,但未經驗證。
終端機
本節不操作。S02~S06 與 S07 的啟動使用系統終端機;S07 的語言選擇與 S08 使用 Terminux 內建終端機。
工作目錄
不適用。
步驟
執行任何命令前,先把 S02~S08 讀過一遍,並為 S02~S06 準備同一個系統終端機視窗。
當 S08 出現單獨一行 hello-terminux 輸出時,本課即完成。從原始碼建置、EDA 流程與 AI provider 屬於其他主題(見附錄)。
預期結果
成果是可互動的 GUI 終端機;本課未驗證 EDA 或 AI 工作流程。
成功驗證
依 S05~S08 確認安裝、Qt 配對、GUI 與獨立指令輸出。
故障處理
如果你需要原始碼建置、EDA 流程或 AI provider,請先完成這份基本安裝,再參考附錄與對應的產品文件;不要為此修改 S02~S08 的步驟。
S02-prereqs — 備妥執行環境並找出 Qt root
影片:R1.1 S02-prereqs 0:12.2–0:28.1
目的
Terminux 需要安裝包以外的 Qt 與部分系統圖形函式庫。先確認你的 Qt root,避免安裝程式執行到一半才停止。
開始前確認
「前置條件」已備妥,或已由系統管理員確認。
你知道 Qt 6.7.3 安裝在哪裡,或能查得到(見「找出你的 Qt root」)。
終端機
系統終端機(Bash),在你的圖形桌面工作階段中開啟。
工作目錄
任意目錄。
步驟
- 把 Qt root 存進 shell 變數
QT_ROOT。出現提示時輸入 絕對路徑(以/開頭)後按 Enter;在這個提示中,開頭的~不會被展開。
read -r -p 'Qt root directory: ' QT_ROOT
- 檢查該資料夾具備 Terminux 需要的結構,且是 Qt 6.7 以上版本:
ls -d "$QT_ROOT/lib" "$QT_ROOT/qml" "$QT_ROOT/plugins" "$QT_ROOT/lib/cmake/Qt6"
grep -h 'set(PACKAGE_VERSION "[0-9]' "$QT_ROOT"/lib/cmake/Qt6/Qt6ConfigVersion*.cmake
- 不要關閉這個終端機視窗。S05 會用到
$QT_ROOT;如果之後開了新的終端機,請在新視窗重做步驟 1。
成功的樣子。 ls -d 原樣印出四個路徑,沒有任何錯誤;grep 印出一行類似 set(PACKAGE_VERSION "6.7.3") 的內容,其中數字就是你的 Qt 版本。這些輸出來自你自己的機器;撰寫本 Guide 時曾以本機 Qt 6.7.3 SDK 檢查過這些輔助命令,但它們不在錄影中。
Terminux 的所有步驟都不需要 sudo。安裝 Qt 或系統套件是本課開始前另外進行的管理工作;本 Guide 不提供 Qt 下載連結或 Qt 安裝步驟。
參數說明
read -r -p '…' QT_ROOT 顯示提示,並把你的輸入存進目前這個 shell 的 QT_ROOT 變數;-r 讓反斜線保持原樣。
ls -d 列出指定的資料夾本身,而不是資料夾內容。只要出現 No such file or directory,就表示該路徑不是可用的 Qt root。
grep -h 'set(PACKAGE_VERSION "[0-9]' … 讀取的版本檔,與 Terminux Qt 檢查器讀取的是同一組 Qt CMake 檔案。
實測版本是 Qt 6.7.3。安裝程式原始碼接受 Qt 6.x 且 ≥ 6.7.0,但 本版本 沒有測試其他版本。
預期結果
你的 Qt root 含有 lib、qml、plugins 與 lib/cmake/Qt6,版本為 Qt 6 且不低於 6.7.0(實測:6.7.3)。實錄環境為 Ubuntu 24.04 x86_64,Qt 6.7.3 位於 /opt/qt673;此路徑只屬錄影環境。
成功驗證
S05/S06 驗相依閉包,S07 再驗實際顯示;offscreen 自查不能證明桌面可用。
故障處理
ls: cannot access …/lib/cmake/Qt6(或 …/qml):多半是選到上層資料夾(裡面有 6.7.3/ 或 gcc_64/)或 bin/ 資料夾。請改用直接包含 lib/、qml/、plugins/ 的資料夾,再重做步驟 1~2。
路徑以 ~ 開頭:重做步驟 1,輸入完整路徑;echo $HOME 可以看到 ~ 代表的路徑。
grep 沒有輸出,或版本低於 6.7.0(例如 6.2.4):這不是合適的 Qt,請向系統管理員取得 Qt 6.7.3。
缺少的系統函式庫,會在之後由安裝程式或 Qt 檢查器以確切檔名列出;請系統管理員安裝提供該檔案的套件。不要設定 LD_LIBRARY_PATH、QT_PLUGIN_PATH 或 QML2_IMPORT_PATH;Terminux 透過自己安裝後的設定找到 Qt。
S03-identify — 確認安裝包身分
必須從獨立且經驗證的可信來源取得安裝包的 SHA256 參考值。與下載檔一起取得的 checksum 只能證明自身一致。若無獨立可信參考值,請在此 STOP:不要解壓或安裝。
sha256sum terminux-0.1.0-linux-x86_64.tar.gz只有完整 digest 與獨立可信參考值完全相符,才能繼續 S04;任何不符、讀取錯誤或來源不明都必須 STOP。不要解壓或安裝。

S04-extract — 解開安裝包
影片:R1.1 S04-extract 0:52.9–1:03.6
目的
安裝程式在壓縮檔裡。先解開,再進入最上層資料夾。
開始前確認
S03 已通過:出現 OK,結束狀態為 0。
此資料夾有足夠空間。
終端機
系統終端機(Bash),與 S03 同一個視窗。
工作目錄
與 S03 相同的資料夾。
步驟
tar -xzf terminux-0.1.0-linux-x86_64.tar.gz && cd terminux-0.1.0
ls
第一個命令完成後,提示字元會以 terminux-0.1.0 結尾。實錄中 ls 列出:LICENSE、README-INSTALL.md、SHA256SUMS、THIRD_PARTY_NOTICES.md、VERSION、gui、install.sh、portable_installer.py、python、third_party、uninstall.sh、wheelhouse。
參數說明
tar -xzf:-x 解開、-z 處理 gzip、-f 指定壓縮檔名。
&& 只在解壓成功後才執行 cd terminux-0.1.0。
ls 列出資料夾內容,用來確認有 install.sh。
預期結果
工作目錄變為 terminux-0.1.0,ls 可見 install.sh。
成功驗證
確認目錄與實際檔案列表,不混用其他包的 installer。
故障處理
gzip: stdin: not in gzip format 或 Unexpected EOF in archive:下載不完整或檔案不對,請回到 S03。
No space left on device:釋放空間或改用其他資料夾,再重新解壓。
列表中沒有 install.sh:用 pwd 確認你位於 terminux-0.1.0。絕對不要改用其他安裝包或其他版本的安裝程式。
S05-install — 以使用者身分安裝 Terminux
影片:R1.1 S05-install 1:03.6–1:34.5(S05-install 1:03.6–1:17.9;S05-result 1:17.9–1:34.5)
目的
把預編譯 GUI、隨包 Python 執行環境與 Terminux engine 安裝到家目錄,並把 Terminux 連結到你的 Qt。過程不編譯、不使用 sudo。
開始前確認
S02 在這個終端機中完成,因此 $QT_ROOT 已設定。
S04 已完成,你位於 terminux-0.1.0。
你的帳號目前沒有執行中的 Terminux 服務。新帳號不會有;否則請見故障處理。
終端機
系統終端機(Bash),與 S02~S04 同一個視窗。
工作目錄
terminux-0.1.0(解開後的資料夾)。
步驟
./install.sh --qt-dir "${QT_ROOT:?QT_ROOT is empty - repeat the S02 Qt root step}" --yes
echo $?
實錄值。 錄影機器執行的是 ./install.sh --qt-dir /opt/qt673 --yes,因為它的 Qt root 是 /opt/qt673。請如上方命令,透過 $QT_ROOT 使用你自己的 Qt root;只有系統管理員確認 Qt 確實在該處時,才可沿用實錄路徑。
安裝程式會做的事(依 本版本 原始碼;結果已在實錄中觀察到):
- 預先檢查:OS、x86_64、glibc、
GLIBCXX_3.4.29與可用空間;若你的帳號仍有執行中的 Terminux 服務,也會停止。 - 依安裝包自己的
SHA256SUMS驗證包內每個檔案。 - 建立
~/.local/opt/terminux/0.1.0.partial,解開隨包 Python,並從wheelhouse/離線安裝 Python 套件。 - 建立指向你 Qt root 的
qt連結,並對這份暫存安裝執行 Qt 檢查。 - 全部通過後,才把資料夾改名為
~/.local/opt/terminux/0.1.0,並把current指向0.1.0。任何一步失敗時,會移除.partial資料夾,current保持不變。 - 在
~/.local/bin/建立兩個小型啟動腳本:terminux與terminux-qt-check。
安裝程式不會修改 ~/.bashrc、~/.profile 或其他 shell 啟動檔。實錄中安裝約花 12 秒;實際時間可能不同。
本版本的安裝程式訊息為繁體中文。 實錄中的重點行:
| 實錄訊息 | 意義 |
|---|---|
預先檢查通過:Ubuntu 24.04.5 LTS x86_64 glibc=2.39 GLIBCXX_3.4.29 可用;可用空間 … bytes。 |
預先檢查通過 |
安裝包 SHA256SUMS 通過。 |
安裝包內容驗證通過 |
Successfully installed …(pip 的英文訊息) |
Python 套件已安裝,但這 不是 最終結果 |
[通過] …(共九行) |
Qt 各項檢查通過;失敗 表示未通過 |
Qt 安裝檢查通過。 |
Qt 檢查通過 |
安裝成功:/home/…/.local/opt/terminux/0.1.0 |
安裝成功 |
current → 0.1.0 |
目前使用的版本為 0.1.0 |
成功行之後,安裝程式還會印出選用提示:Bash 與 tcsh 的 PATH 設定、tcsh hook、啟動命令 ~/.local/bin/terminux、LLM 設定為選用、移除命令,以及多台主機共用安裝時 Qt 與安裝路徑必須相同。請見附錄。
安裝後的配置
| 路徑 | 說明 |
|---|---|
~/.local/opt/terminux/0.1.0/ |
版本資料夾:GUI、Python 環境、engine |
~/.local/opt/terminux/current |
指向 0.1.0 的連結;只在安裝成功後切換 |
~/.local/opt/terminux/0.1.0/qt |
指向你 Qt root 的連結;請勿移動 Qt |
~/.local/bin/terminux |
啟動 Terminux 的啟動腳本 |
~/.local/bin/terminux-qt-check |
S06 使用的 Qt 檢查器啟動腳本 |
~/.terminux/ |
你的執行資料、設定與 log;首次啟動時建立 |

參數說明
--qt-dir 是 S02 取得的外部 Qt root。"${QT_ROOT:?…}" 的寫法會在 QT_ROOT 為空時(例如在新的終端機)直接顯示訊息並停止,不會執行安裝程式。
--yes 自動回答安裝程式的確認提問;它 不會 略過平台、ABI、Qt 或執行中服務的檢查。
預設安裝位置是 ~/.local/opt/terminux。原始碼另有 --prefix(改用其他位置)、--no-bin-link(不在 ~/.local/bin 建立啟動腳本)、--reinstall 與 --force;本課沒有使用或測試。--force 只略過「不支援的 OS」檢查,絕不能用來解決 ABI 或 Qt 問題。
預期結果
實際 installer 顯示安裝成功及 current → 0.1.0,結束狀態為 0。
成功驗證
確認可見成功行與立即查得的結束狀態,再完成 S06;只見 pip 成功不足以證明整包安裝成功。
故障處理
bash: QT_ROOT: QT_ROOT is empty - repeat the S02 Qt root step:安裝程式沒有執行。請在這個終端機重做 S02 步驟 1,再重新執行 S05。
Terminux:不支援的平台:…、Terminux:只支援 x86_64。、Terminux:glibc … 低於必要的 2.34。 或 Terminux:系統 libstdc++ 未提供 GLIBCXX_3.4.29;請洽系統管理員。:系統不在支援範圍。請洽系統管理員,不要加 --force。
Terminux:空間不足:需要 … bytes,可用 … bytes。:釋放該檔案系統的空間後,重新執行 S05。
Terminux:daemon 仍在執行(pid=…)… 或 Terminux:owner 位於其他主機 …:請在服務實際執行的主機上,用原本的方式停止它(在原啟動終端機按 Ctrl+C,或使用原服務管理方式)。不要使用 pkill,也不要刪除 lock 檔。
出現 [失敗] …,接著是 已清除 partial:…;current 未變動。:缺少 Qt 元件或函式庫。閱讀 [失敗] 那一行,並參考 S06 的故障處理。
Terminux:同版本已安裝:…;如需重裝,請加 --reinstall。:0.1.0 已經安裝,可以直接進行 S06。只有在明確決定重裝時才使用 --reinstall。
Terminux:partial 已存在,請先人工確認:…:先前的嘗試留下了 partial 資料夾。不要直接刪除;先確認沒有其他安裝正在進行,再聯絡支援窗口。
警告:保留非本安裝建立的檔案 …/.local/bin/terminux。:已存在一個不是本安裝程式建立的檔案,因此 ~/.local/bin/terminux 可能不是 Terminux 的啟動腳本。進行 S07 前,請先確認該檔案是什麼。
echo $? 印出的不是 0:安裝沒有完成。請保留完整輸出以便支援人員查因。
S06-check — 檢查安裝版本與 Qt 配對
影片:R1.1 S06-check 1:34.5–1:52.5
目的
開啟 GUI 前,先確認目前使用的版本,以及安裝後的程式能從你的 Qt 載入所需的一切。
開始前確認
S05 結尾出現 安裝成功,且結束狀態為 0。
S02 的 Qt root 仍在原處且可讀取。
終端機
系統終端機(Bash)。
工作目錄
任意目錄。命令使用完整路徑,不受 PATH 或目前資料夾影響。
步驟
readlink ~/.local/opt/terminux/current
~/.local/bin/terminux-qt-check --qt-dir ~/.local/opt/terminux/current/qt --prefix ~/.local/opt/terminux/current
echo $?
readlink 印出 0.1.0。檢查器的實錄輸出(皆為繁體中文):
| 實錄訊息 | 意義 |
|---|---|
[通過] Qt 6.7.3(需求 Qt 6.x ≥ 6.7.0) |
Qt 版本符合需求 |
[通過] Qt 函式庫(31 項) |
找到 31 個 Qt 函式庫 |
[通過] QML import(25 項) 與 [通過] QML plugin(25 項) |
找到所需的 QML 模組 |
[通過] 平台 plugin(2 項) |
找到 xcb 與 offscreen 平台 plugin |
[通過] xcb plugin 的 ldd 無缺少函式庫 |
X11(xcb)plugin 沒有缺少系統函式庫 |
[通過] qt symlink 與 qt.conf |
安裝後的 qt 連結與 Qt 設定一致 |
[通過] terminux --self-check exit=0 |
GUI 程式能以 offscreen 方式啟動並載入 Qt |
[通過] dqe_viewer --self-check exit=0 |
隨附的 viewer 程式能以 offscreen 方式啟動並載入 Qt |
Qt 安裝檢查通過。 |
整體:Qt 檢查通過 |
兩項自我檢查都以 offscreen 方式執行:不會開啟視窗,也不能證明你的桌面顯示可用;這要到 S07 才驗證。它們也不是 DQE 資料流程測試。

參數說明
readlink ~/.local/opt/terminux/current 顯示 current 指向哪裡。它只確認連結,不代表完整的程式版本或相容性檢查。
檢查器的 --qt-dir ~/.local/opt/terminux/current/qt 是安裝後指向 Qt 的 連結,而不是直接用 $QT_ROOT,因此連結本身也會被檢查。
檢查器的 --prefix ~/.local/opt/terminux/current 是安裝後的 版本資料夾,與安裝程式的預設位置 ~/.local/opt/terminux 意義不同。
緊接在檢查器之後的 echo $?:0 表示全部檢查通過。
預期結果
readlink 顯示 0.1.0;Qt 6.7.3、庫、imports、plugins、配置與兩個自查皆通過,checker 結束狀態為 0。
成功驗證
確認 checker 所有成功行與立即結束狀態;這不是 production DQE 或真正桌面顯示測試。
故障處理
readlink 沒有輸出或顯示 No such file or directory:S05 沒有完成,請回到 S05。
[失敗] Qt 目錄不存在或 symlink 目標無效:…:Qt root 被移動、改名或未掛載。請把 Qt 恢復到原路徑;Terminux 預期它在那裡。
[失敗] 缺少系統函式庫 libxxx.so.N;EL9:…;Ubuntu 24.04:…:該行會列出對應套件。請系統管理員安裝後,再重新執行 S06。
[失敗] 缺少 QML import:…、缺少 QML plugin:… 或 缺少 Qt 函式庫:Qt 安裝不完整,需由系統管理員補齊同一版本的缺漏元件。
[失敗] qt.conf 配置:… 或某個 self-check 失敗:不要用環境變數繞過;保留完整輸出(含其下方各行)交給支援人員。
S07-launch — 啟動 Terminux 並選擇介面語言
影片:R1.1 S07-launch 1:52.5–2:35.0(S07-start 1:52.5–1:59.9;S07-language-switch 1:59.9–2:27.0;S07-relaunch 2:27.0–2:35.0)
目的
從安裝後的啟動器開啟真正的 Terminux 視窗。新帳號首次開啟時介面可能是繁體中文;本步驟說明實錄中如何切換成英文。
開始前確認
S06 已通過。
你以同一使用者登入這台主機的圖形桌面工作階段(不是沒有顯示的純 SSH 連線)。
Terminux 內建終端機的 Bash 會自動整合,不需修改 ~/.bashrc;也不需要 AI provider、EDA 工具或 project ID。
終端機
從 系統終端機 啟動 Terminux;在 Terminux 內建終端機(Terminux 視窗中顯示 shell 提示字元的區域)選擇語言。
工作目錄
任意目錄。
步驟
- 啟動 Terminux:
~/.local/bin/terminux
啟動器幾乎會立刻回到系統終端機的提示字元,這是正常的:它會在需要時啟動 Terminux 背景服務,然後開啟視窗。首次啟動時視窗可能稍慢出現,因為啟動器最多會等待約 30 秒讓服務就緒。
-
先確認目前語言:在 Terminux 內建終端機(有提示字元的區域)按右鍵,開啟 Language 子選單。即使語言設定是繁體中文,視窗選單
View與Help仍可能顯示英文,所以它們不能代表目前設定;請看 Language 子選單中哪一項有勾選。若 English 已勾選,直接進行 S08。若勾選的是繁體中文,請選 English。實錄中這兩個選單項目顯示為英文。 -
目前開啟的視窗不會有明顯變化,也不會出現重新啟動的對話框;選擇已經儲存。以一般方式關閉 Terminux 視窗(視窗的關閉按鈕,或如錄影中按 Alt+F4)。
-
在系統終端機用同一個命令再次啟動 Terminux:
~/.local/bin/terminux
重新啟動後,實錄畫面顯示英文的視窗選單 View 與 Help、視窗底部的狀態文字 Terminux service ready,以及 Terminux 內建終端機中的 shell 提示字元。
Terminux service ready 是短暫的狀態訊息:視窗與提示字元仍在時它可能已經消失,沒看到它不代表失敗。請以視窗已開啟並有 shell 提示字元、Language 子選單中 English 已勾選,以及 S08 的輸出來判斷重啟結果;只有出現實際的錯誤訊息時才停止並保留訊息供支援使用(見故障處理)。
關閉視窗不一定會停止 Terminux 背景服務,這是預期行為;下次啟動會沿用它。語言選擇會存在 Terminux 設定中;請不要手動編輯設定檔來切換語言。

參數說明
~/.local/bin/terminux 是 S05 建立的啟動腳本,它會呼叫 ~/.local/opt/terminux/current 底下安裝的啟動器。即使 ~/.local/bin 不在 PATH 中,完整路徑也能使用(見附錄 A)。
不需要任何參數。
預期結果
真正重啟後可見英文介面文字與可輸入的 prompt,且 Language 子選單勾選 English。短暫的狀態訊息 Terminux service ready 可能出現後消失。
成功驗證
launcher 可能在 GUI 關閉前就回到系統 prompt;請確認真正 GUI、Language 子選單中已勾選 English,以及 S08 輸出,不要以是否看見短暫的 Terminux service ready 訊息作判準。關 GUI 不代表 daemon 已停止。
故障處理
bash: …/.local/bin/terminux: No such file or directory:S05 沒有完成,或啟動腳本沒有建立(見 S05 的 警告:保留非本安裝建立的檔案 情況)。
沒有視窗,並出現 TERM_LAUNCH_FAILED … 或 TERM_LAUNCH_GUI_NOT_FOUND 等訊息:重新執行 S06;若通過,確認你是在這台主機的圖形工作階段中操作。請保留完整訊息給支援人員。
TERM_LAUNCH_DAEMON_NOT_READY…:服務在 30 秒內沒有回報就緒,shell 整合可能尚未部署。若視窗已開啟就先關閉,再啟動一次;若訊息重複出現,請保留給支援人員。
TERM_LAUNCH_WRAPPER_SETUP failed 或 disabled:自動 shell 整合沒有部署。訊息會指出要查看的 log 檔。S08 可能仍可通過,但整合功能未經確認(見附錄 B)。
TERM_DAEMON_OWNER_UNAVAILABLE host=… pid=…:你的帳號有另一個 Terminux 服務(可能在共用家目錄的另一台主機上)占用執行環境。在支援窗口確認那個服務確實已不存在之前,不要刪除 lock 檔,也不要執行訊息中提到的 reset。
重新啟動後仍是中文:確認你是在 Terminux 內建終端機的右鍵選單中選了 English、關閉了視窗,並從系統終端機重新啟動。不要用環境變數或修改設定檔強制切換。
S08-verify — 驗證 Terminux 內建終端機
影片:R1.1 S08-verify 2:35.0–3:03.3(S08-verify 2:35.0–2:51.5;S08-recap 2:51.5–3:03.3)
目的
用一個不需要 EDA 工具或 AI provider 的普通指令,確認 Terminux 內建終端機能接受鍵盤輸入、執行命令並顯示輸出。
開始前確認
S07 開啟的 Terminux 視窗仍在,並顯示 shell 提示字元。
終端機
Terminux 內建終端機(Terminux 視窗內),不是系統終端機。
工作目錄
Terminux 提示字元顯示的任何資料夾皆可。
步驟
在 Terminux 內建終端機中點一下,讓它取得鍵盤焦點,輸入下列命令後按 Enter:
echo hello-terminux
如何判讀結果。 你輸入的那一行本身也含有 hello-terminux,那不算證據。成功的標準是:在命令下方出現 獨立的一行輸出,內容只有 hello-terminux,接著出現新的提示字元。
實錄中,命令與輸出之間出現了一行以 [1]+ Done 開頭、以 terminux-notify post_exec … 結尾的訊息。這是自動 shell 整合產生的背景工作通知,既不是錯誤,也不是成功的證據;不必理會。
完成了。 之後要再次啟動 Terminux,請在系統終端機執行 ~/.local/bin/terminux;若已把 ~/.local/bin 加入 PATH,也可以只輸入 terminux(見附錄 A)。
這個結果只證明 Terminux 內建終端機可用,不代表 EDA 工具、wrapper、DQE 流程或 AI provider 已就緒。

參數說明
echo 會印出它的參數;hello-terminux 只是一個容易辨識的字,沒有任何 Terminux 專用參數。
預期結果
指令下方有獨立 hello-terminux stdout 行,之前可能有真正的 Done 行,接著回到 prompt。
成功驗證
輸入列本身不算證據;獨立 stdout 只驗證這段終端機互動,不代表 AI/EDA 就緒。
故障處理
輸入時畫面沒有反應:在終端機區域點一下取得焦點,並確認有顯示提示字元。
只有你輸入的那一行,沒有獨立的 hello-terminux 行:在空白行按一次 Enter 後再看。若仍沒有,請截圖保留給支援人員。不要為了讓畫面乾淨而刪除 ~/.terminux、重設設定或停用 shell 整合。
hello-terminux 之前出現 Done 行:屬預期現象,檢查已通過。
故障處理速查
| 症狀 | 參考章節 |
|---|---|
ls: cannot access …/lib/cmake/Qt6 或 Qt 版本不符 |
S02 |
FAILED、did NOT match 或沒有 OK |
S03 — STOP,不要解壓或安裝 |
gzip: stdin: not in gzip format、找不到 install.sh |
S04 |
bash: QT_ROOT: QT_ROOT is empty … |
S05 — 在同一個終端機重做 S02 |
Terminux:不支援的平台…、glibc … 低於必要的 2.34、GLIBCXX_3.4.29 |
S05 — 系統不在支援範圍 |
Terminux:daemon 仍在執行… 或 owner 位於其他主機… |
S05 — 仍有 Terminux 服務在執行 |
[失敗] … |
S06 — 該行會指出缺少的項目 |
沒有視窗、出現 TERM_LAUNCH_… 訊息 |
S07 |
| 重新啟動後介面仍是中文 | S07 |
只看到輸入列,沒有獨立的 hello-terminux 行 |
S08 |
每一步都適用的原則:保留完整錯誤輸出;不要刪除 ~/.terminux 或 ~/.local/opt/terminux 底下的檔案;不要用 pkill、rm -rf 或 --force 當作修復;不要設定 LD_LIBRARY_PATH、QT_PLUGIN_PATH 或 QML2_IMPORT_PATH。請改為帶著輸出內容聯絡支援窗口。
附錄 A — 選用:較短的啟動命令(PATH)
不是必要步驟;完整路徑 ~/.local/bin/terminux 一定可用。若想只輸入 terminux,可把 ~/.local/bin 加進 PATH,例如在 ~/.bashrc 加入下面這行,再開新的終端機:export PATH="$HOME/.local/bin:$PATH"。可用 type terminux 確認,應顯示位於你家目錄的 .local/bin/terminux。此便利設定 未在 本版本 實錄中測試;實錄只使用完整路徑。
附錄 B — Shell 整合與工具 wrapper
以下功能都不是 S01~S08 的前置條件。
- Terminux 內建終端機的 Bash 會自動整合。首次啟動時 Terminux 服務會部署 shell hook;內建終端機以自己的啟動檔執行 Bash,先載入你的
~/.bashrc,再載入 hook。你不需要修改~/.bashrc。(;實錄中 shell 啟動檔前後未變,S08 指令正常。本版本 未跑完整 hook 回歸測試。) - 外部終端機(你平常的系統終端機)不會自動整合。需要者可自行在 shell 啟動檔中 source
~/.terminux/bash_hooks.sh以選擇加入。(;本版本 未測試。) - 工具 wrapper 位於
~/.terminux/bin/,由服務的自動設定部署。它們把呼叫轉交給真正的工具,讓 Terminux 能觀察執行;它們本身不是工具,也不會安裝任何 EDA 軟體。這和只負責啟動 Terminux 的~/.local/bin/terminux不同。設定TERMINUX_AUTO_SETUP_WRAPPERS=0會停用自動設定。(;本版本 未做端到端驗證。) - 若啟動器印出
TERM_LAUNCH_WRAPPER_SETUP failed或disabled,hook 可能沒有部署;訊息會指出要查看的 log。視窗能開、echo能跑,都不代表整合已就緒。
附錄 C — tcsh/csh 使用者
本 Guide 的步驟使用 Bash。tcsh 使用者可參考安裝程式印出的提示(;本版本 未測試,其他版本可能不同):
- PATH:
setenv PATH "$HOME/.local/bin:$PATH" - Hook:在
~/.tcshrc加入if ( $?TERMINUX_ACTIVE ) source ~/.terminux/tcsh_hooks.csh;只有沒有~/.tcshrc時才加到~/.cshrc。TERMINUX_ACTIVE只在 Terminux 內建終端機中設定,不影響其他 shell。 - tcsh 的
$?意義不同($?NAME用來測試變數是否存在);查結束狀態請用echo $status。S02 與 S05 使用的read與${QT_ROOT:?…}是 Bash 專用寫法,因此 S02~S06 請在 Bash 中執行。 - 傳統 csh 沒有 tcsh 的 hook 功能。
附錄 D — EDA 工具、流程與 DQE
不是基本安裝的前置條件,且 本版本 未做端到端驗證。
- 安裝 Terminux 不會安裝任何 EDA 工具。實際流程需要你自己已安裝並取得授權的工具、工具執行環境、可用的 flow 腳本與輸入資料。
- wrapper 存在,不代表真正的工具存在或可執行。
- S06 的
dqe_viewer --self-check只代表隨附的 viewer 程式能以 offscreen 方式啟動並載入 Qt,不是 DQE 資料流程測試。 - 若出現選用 STA playbook 無法使用的訊息,屬本版本的已知限制,不影響 S01~S08。
附錄 E — AI/LLM provider
選用功能。未設定 provider 時,Terminux 不會發出 LLM 請求,S01~S08 也不需要 provider。本安裝包只含基本相依;Gemini、Anthropic、local-LLM 與 RAG 的額外套件未包含,需另行準備。provider 設定方式請見產品 README 中 LLM provider 與憑證的段落,本版本 未測試。影片 S02 提到的「核准來源」指 Qt 的提供來源,不是 AI provider。
附錄 F — 移除(僅供參考,本課未執行)
安裝程式會印出此版本的移除命令:~/.local/opt/terminux/0.1.0/uninstall.sh --version 0.1.0。依原始碼,它預設保留 ~/.terminux 中的資料、設定與 log;只有明確加上 --purge-data 才會清除,且需要輸入完整資料路徑確認。它不會修改你的 shell 啟動檔;你自行加入的 hook 行需自行移除。本版本 實錄沒有執行移除。
附錄 G — 平台與操作限制
- 只實測過 Ubuntu 24.04 x86_64、Qt 6.7.3、Xorg 桌面。其他 Qt 版本、EL9、Wayland、遠端顯示與 GPU 加速皆未驗證。
- 若多台主機共用同一個家目錄,每台主機都需要相同路徑的 Qt 與相同的安裝路徑(安裝程式訊息);此情境未測試。
- 最低 CPU、記憶體與安裝耗時尚未量測。