Skip to content

AppImage

AppImage는 배포판에 설치하지 않고 단일 실행 파일로 동작하는 Linux 애플리케이션 패키징 포맷이다. 내부적으로 SquashFS 이미지를 FUSE로 마운트해 실행하므로, 실행 환경의 FUSE 지원 여부 및 (Electron 앱의 경우) 샌드박스·디스플레이 설정에 따라 실행이 막히는 경우가 있다.

Categories

실행

FUSE 없이 임시 추출 실행

FUSE가 없을 때 마운트 대신 임시 디렉터리로 추출해서 실행한다. 

./App.AppImage --appimage-extract-and-run
# 또는 / or
APPIMAGE_EXTRACT_AND_RUN=1 ./App.AppImage

내용물만 추출 

./App.AppImage --appimage-extract   # squashfs-root/ 디렉터리로 추출

AppImageUpdate

Python packaging

Troubleshooting

여러 개의 실행파일 포함

libfuse.so.2 로딩 실패 

dlopen(): error loading libfuse.so.2

"주의"

Ubuntu 24.04 에서 (HP 랩탑) 에서 fuse, libfuse2 패키지 설치하면 부팅시 GNOME 이 출력되지 않는 이슈 발생하더라

AppImage는 실행에 FUSE 2가 필요하다. 라이브러리가 없으면 마운트에 실패한다. 앱 자체의 문제가 아니라 실행 환경에 FUSE가 없는 것이다.

해결 1 — 추출 실행
FUSE 없이 바로 띄운다. (위 #FUSE 없이 임시 추출 실행 참고) 
./App.AppImage --appimage-extract-and-run
해결 2 — FUSE(libfuse2) 설치 
sudo apt install libfuse2
Ubuntu 22.04+/24.04에서는 패키지명이 libfuse2 또는 libfuse2t64이다. 설치 후에는 --appimage-extract-and-run 없이 그대로 실행된다.

chrome-sandbox SUID 샌드박스 오류 (Electron 앱) 

The SUID sandbox helper binary was found, but is not configured correctly... chrome-sandbox is owned by root and has mode 4755

Chromium의 SUID 샌드박스 헬퍼(chrome-sandbox)가 root 소유·4755 권한이 아니어서 중단된 경우다. 최근 Ubuntu(23.10+)가 AppArmor로 비특권 user namespace를 제한하면서 Electron이 SUID 샌드박스로 폴백하는데, /tmp에 추출된 헬퍼는 setuid 권한을 가질 수 없어 발생한다.

방법

명령

샌드박스

비고

즉시 확인

./App.AppImage --appimage-extract-and-run --no-sandbox

:틀:Cross

동작 확인용

sysctl 완화

아래 sysctl 적용 후 실행

:틀:Tick

시스템 전역 설정 변경

deb 설치 (권장)

dpkg -i App.deb 후 실행

:틀:Tick

배포에 적합, root:4755 자동 설정

sysctl로 비특권 user namespace 제한 완화 
# 일시 적용 / temporary
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
# 영구 적용 / persistent
echo 'kernel.apparmor_restrict_unprivileged_userns=0' \
  | sudo tee /etc/sysctl.d/60-apparmor-namespace.conf

이후 샌드박스를 켠 채로 정상 실행된다. .deb 설치 시에는 chrome-sandbox가 root:4755로 세팅되므로 --no-sandbox 없이 동작한다.

Missing X server or $DISPLAY 

Missing X server or <code>$DISPLAY</code> ... The platform failed to initialize.

현재 셸에 디스플레이 서버가 연결되어 있지 않다는 뜻이다($DISPLAY 없음). 앱 버그가 아니라 GUI를 띄울 화면이 없는 환경 문제다. 먼저 환경을 확인한다. 

echo "DISPLAY=$DISPLAY WAYLAND=$WAYLAND_DISPLAY SESSION=$XDG_SESSION_TYPE SSH=$SSH_CONNECTION"
경우 1 — Wayland 세션 (Ubuntu 기본, 가장 흔함)
Electron이 X11로 폴백하다 실패한 것. Ozone Wayland로 띄운다. 
./App.AppImage --appimage-extract-and-run --no-sandbox --ozone-platform-hint=auto
경우 2 — SSH 원격 접속
GUI를 로컬 화면에 띄우려면 X11 포워딩으로 재접속한다. 
ssh -Y user@host
./App.AppImage --appimage-extract-and-run --no-sandbox --disable-gpu
경우 3 — 진짜 헤드리스 (모니터 없음)
가상 디스플레이(Xvfb)로 부팅·렌더만 검증하고 스크린샷으로 확인한다. 
sudo apt install -y xvfb imagemagick
xvfb-run -a --server-args="-screen 0 1100x780x24" bash -c '
  ./App.AppImage --appimage-extract-and-run --no-sandbox --disable-gpu &
  sleep 7; import -window root /tmp/app.png; kill %1 2>/dev/null'

See also

Favorite site