VS Code Remote 환경에서 'cannot open display' 에러 해결 가이드
이 문서는 VS Code의 Remote-SSH 환경에서 GUI 애플리케이션 실행 시 발생하는 Gtk-WARNING **: cannot open display 또는 Error: Can't open display 에러를 해결하는 전체 과정을 정리한 가이드입니다.
Symptoms (문제 증상)
원격 서버에 SSH로 접속한 VS Code 터미널에서 xeyes 등 GUI가 필요한 프로그램을 실행하면, 다음과 같은 에러 메시지가 출력되며 프로그램이 실행되지 않는다.
Error: Can't open display:(process:123): Gtk-WARNING **: cannot open display:
Troubleshooting Steps (문제 해결 단계)
문제는 클라이언트(내 PC) ↔ SSH 연결 ↔ 서버 간의 그래픽 데이터 전달(X11 포워딩) 과정 어딘가에 있습니다. 아래 단계를 순서대로 진행합니다.
1단계: 기본 X11 포워딩 설정 확인
가장 먼저 확인해야 할 기본적인 설정입니다.
1-1. 로컬 PC에 X 서버 설치 및 실행
원격 서버의 그래픽을 내 PC 화면에 표시해 줄 프로그램입니다.
- Windows: VcXsrv 설치를 권장.
- [중요] 실행 시(XLaunch)
Disable access control옵션을 반드시 체크해야 합니다.
- [중요] 실행 시(XLaunch)
- macOS: XQuartz 설치 후 실행.
- 환경설정 > 보안 > "네트워크 클라이언트에서의 연결 허용" 체크.
Note: X 서버는 SSH로 접속하기 전에 항상 먼저 실행되어 있어야 합니다.
1-2. VS Code SSH 설정 파일 수정
내 PC에서 서버로 접속할 때 X11 포워딩을 요청하도록 설정합니다.
- VS Code에서
Ctrl+Shift+P>Remote-SSH: Open Configuration File...선택. ~/.ssh/config파일에 접속하려는 호스트(Host) 정보에 아래 두 줄을 추가합니다.Host my-remote-server HostName <서버 IP 주소> User <사용자명> ForwardX11 yes ForwardX11Trusted yes
1-3. 원격 서버 SSH 서비스 설정 확인
원격 서버가 클라이언트의 X11 포워딩 요청을 허용하도록 설정합니다.
- 원격 서버 터미널에서
/etc/ssh/sshd_config파일을 엽니다 (sudo권한 필요).sudo nano /etc/ssh/sshd_config - 파일 안에 다음 내용이
yes로 설정되어 있는지 확인합니다.X11Forwarding yes - 만약 파일을 수정했다면, SSH 서비스를 반드시 재시작하여 설정을 적용합니다.
sudo systemctl restart sshd
2단계: 연결 및 인증 문제 진단
기본 설정 후에도 문제가 지속될 경우, 연결 과정의 세부 문제를 확인합니다.
2-1. 간단한 GUI 앱(xeyes)으로 테스트
복잡한 프로그램 대신, 간단한 xeyes로 포워딩 자체의 성공 여부를 테스트하여 문제 범위를 좁힙니다.
# 설치 (필요시)
sudo apt update
sudo apt install x11-apps
# 실행
xeyes2-2. xauth 패키지 및 인증 쿠키 확인
X11 포워딩은 xauth를 통한 인증 방식을 사용합니다. 원격 서버에서 이 기능이 정상적으로 동작하는지 확인합니다.
# xauth 패키지가 설치되어 있는지 확인
which xauth
# 현재 SSH 세션의 인증 쿠키(매직 쿠키)가 생성되었는지 확인
xauth list정상 응답:
xauth list실행 시ubuntu-node/unix:10 MIT-MAGIC-COOKIE-1과 같이MIT-MAGIC-COOKIE-1을 포함한 내용이 출력되어야 합니다.
2-3. 방화벽 설정 확인 (Windows)
로컬 PC의 Windows 방화벽이 X 서버(VcXsrv)의 네트워크 통신을 차단할 수 있습니다.
- Windows 검색창에서 **
방화벽 및 네트워크 보호**를 검색하여 실행합니다. 방화벽에서 앱 허용메뉴를 클릭합니다.VcXsrv를 찾아개인및공용네트워크에 대해 모두 허용으로 체크되어 있는지 확인하고, 아니라면 설정을 변경하여 허용해 줍니다.
3단계: 최종 원인 분석 및 해결 (클라이언트 환경 문제)
모든 서버 및 SSH 설정이 올바른데도 $DISPLAY 변수가 설정되지 않는(Error: Can't open display:) 문제의 해결 단계입니다.
3-1. SSH 상세 로그(ssh -v) 분석
문제의 원인은 SSH 연결 과정의 상세 로그를 통해 파악할 수 있습니다. PC의 터미널(PowerShell, CMD)에서 아래 명령을 실행하여 로그를 확인합니다.
ssh -vY <user>@<server_ip>로그 분석 결과, 아래와 같은 핵심 메시지가 발견되었습니다.
debug1: X11 forwarding requested but DISPLAY not set
정확한 원인: SSH 클라이언트(내 PC)가 X11 포워딩을 서버에 요청하려 했으나, 로컬 PC(Windows) 자체에
DISPLAY환경 변수가 설정되어 있지 않아 요청을 시작조차 하지 못한 것입니다.
3-2. 최종 해결: Windows에 DISPLAY 전역 환경 변수 설정
VS Code를 포함한 모든 프로그램이 로컬 X 서버의 위치를 알 수 있도록 Windows 시스템에 환경 변수를 영구적으로 설정하여 문제를 해결합니다.
- Windows 검색에서 **
시스템 환경 변수 편집**을 실행합니다. 환경 변수버튼을 클릭합니다.사용자 변수섹션에서새로 만들기를 클릭합니다.- 아래 정보를 입력하고 저장합니다.
- 변수 이름:
DISPLAY - 변수 값:
127.0.0.1:0.0
- 변수 이름:
- 모든 VS Code 창을 완전히 종료한 후 다시 실행하여 변경된 설정을 시스템에 적용합니다.
이 설정으로 인해, VS Code의 Remote-SSH를 포함한 모든 SSH 클라이언트는 로컬 X 서버의 위치를 명확하게 인지하게 되어 X11 포워딩이 정상적으로 동작하게 됩니다.
-----
## ++ 도커 컨테이너 GUI 연동 핵심 요약
도커 컨테이너에서 GUI 앱을 실행하려면, 컨테이너에 **화면 접속 티켓(Display Ticket)**을 전달해줘야 합니다.
이 티켓은 **3가지 요소**로 구성되며, `docker run` 명령어에 아래 옵션을 추가하여 전달합니다.
1. **화면 주소 (`DISPLAY` 변수)**
- 그래픽을 어디에 표시할지 알려줍니다.
- **옵션:** `--env="DISPLAY=$DISPLAY"`
2. **인증키 (`.Xauthority` 파일)**
- 해당 화면에 접근할 수 있는 권한을 부여합니다.
- **옵션:** `--volume="$HOME/.Xauthority:/root/.Xauthority:rw"`
3. **네트워크 통로 (`Host` 네트워크)**
- 컨테이너가 화면 주소로 실제로 통신할 수 있는 길을 열어줍니다.
- **옵션:** `--net=host`
### 최종 명령어 템플릿
```bash
docker run -it --rm \
--env="DISPLAY=$DISPLAY" \
--volume="$HOME/.Xauthority:/root/.Xauthority:rw" \
--net=host \
<이미지 이름>
```
