VSCode launch.json 설정, ComfyUI main.py 디버깅하기

ComfyUI 소스를 VS Code에서 직접 수정하다 보면 터미널에서 매번 python main.py를 실행하는 대신 F5로 서버를 시작하고 breakpoint에서 멈추고 싶을 때가 있다. 이때 사용하는 파일이 workspace의.vscode/launch.json이다.

ComfyUI 디버깅에서 중요한 것은 launch.json을 복잡하게 만드는 것이 아니다. program이 ComfyUI의 main.py를 가리키는지, cwd가 ComfyUI 루트인지, 평소 터미널에서 붙이던 실행 옵션이 args에 들어가는지만 먼저 맞추면 된다.

vscode launch json 설정에서 가장 먼저 볼 변화

launch.json의 program은 main.py로 고정한다

VS Code Python Debugger의 program은 디버거가 실행할 Python 시작 파일을 지정한다. 기본 Python File 설정에서는 현재 열려 있는 ${file}을 실행할 수 있지만, ComfyUI처럼 항상 정해진 진입점으로 시작해야 하는 프로젝트에서는 이 방식이 불편할 수 있다.

ComfyUI의 Python 백엔드는 저장소 루트의 main.py를 시작점으로 실행한다. 따라서 ComfyUI 폴더 자체를 VS Code workspace로 열었다면 program을 ${workspaceFolder}/main.py처럼 고정하는 방식이 이해하기 쉽다.

${file}보다 main.py 고정이 편한 이유

program을 ${file}로 두면 F5를 누르는 순간 현재 편집 중인 Python 파일이 실행 대상이 된다. Custom Node 파일이나 내부 모듈을 열어 둔 상태라면 ComfyUI 서버 자체가 아니라 그 파일을 직접 실행하려는 상황이 생길 수 있다.

반대로 main.py를 고정하면 어떤 소스 파일을 보고 있더라도 F5의 시작점은 동일하다. breakpoint는 다른 Python 파일에 걸어 두더라도 실제 실행 흐름은 ComfyUI 서버에서 시작한다.

즉 launch.json의 목적은 현재 보고 있는 파일을 실행하는 것이 아니라, 평소 python main.py로 시작하던 ComfyUI 실행을 VS Code 디버거가 대신 시작하도록 만드는 데 있다.

cwd는 ComfyUI 루트로 맞춘다

cwd는 디버깅 프로세스의 현재 작업 디렉터리를 결정한다. Python 코드에서 상대 경로로 파일이나 디렉터리를 참조하면 이 값의 영향을 받을 수 있다.

vscode launch json 설정가 ComfyUI 워크플로우에 미치는 영향

ComfyUI를 workspace 루트로 열어 사용한다면 cwd 역시 ${workspaceFolder}로 맞추는 구성이 단순하다. 그러면 main.py와 ComfyUI의 여러 디렉터리를 기준으로 실행하는 환경을 유지하기 쉽다.

기존 방식과 비교해야 할 부분

program과 cwd는 같은 역할이 아니다

program은 어떤 Python 파일을 실행할지를 결정한다. cwd는 실행된 프로그램이 어느 폴더를 현재 작업 위치로 볼지를 결정한다.

따라서 main.py의 절대 위치만 정확하게 지정했다고 cwd까지 자동으로 같은 의미가 되는 것은 아니다. ComfyUI 디버깅 설정을 만들 때 두 값을 따로 확인하는 이유다.

특히 ComfyUI 폴더의 상위 디렉터리를 VS Code workspace로 열었다면 ${workspaceFolder}가 실제 ComfyUI 루트와 달라질 수 있다. 이 경우 program과 cwd 모두 실제 ComfyUI 디렉터리를 기준으로 다시 맞춰야 한다.

ComfyUI 실행 옵션은 args에 넣는다

터미널에서 ComfyUI를 실행할 때 python main.py --listen 0.0.0.0 --port 8188처럼 옵션을 붙여 사용했다면 launch.json에서도 같은 역할을 하는 부분이 args다.

VS Code Python 디버깅 설정의 args는 실행할 Python 프로그램으로 전달할 command-line arguments를 배열 형태로 지정한다. 옵션과 값을 각각 별도 항목으로 나누어 넣는 방식이 기본이다.

ComfyUI는 현재 --listen과 --port를 비롯한 여러 startup flag를 제공한다. 기본 listen 주소는 127.0.0.1이고 기본 port는 8188이므로, 기본값 그대로 사용할 경우 반드시 두 옵션을 추가해야 하는 것은 아니다.

성능과 결과 품질에서 확인할 차이

워크플로우 구성에서 놓치기 쉬운 부분

반대로 LAN에서 접근하도록 ComfyUI를 실행하거나 다른 포트를 사용해 왔다면 기존 명령줄 옵션을 launch.json의 args에도 반영해야 평소와 같은 조건으로 디버깅할 수 있다.

Python 인터프리터와 integratedTerminal도 확인한다

launch.json의 program과 cwd가 맞는데 ComfyUI가 실행되지 않는다면 Python 환경을 확인해야 한다. VS Code Python Debugger는 별도의 python 값을 지정하지 않을 경우 workspace에서 선택한 Python interpreter를 기준으로 디버깅할 수 있다.

따라서 터미널에서는 ComfyUI 전용 가상환경을 사용하면서 VS Code에서는 다른 Python을 선택해 둔 경우 dependency 차이로 실행 결과가 달라질 수 있다. ComfyUI가 정상적으로 실행되던 Python 환경을 VS Code에서도 선택하는 것이 중요하다.

integratedTerminal로 로그를 같이 본다

ComfyUI처럼 서버 로그를 계속 확인해야 하는 프로그램은 console을 integratedTerminal로 두면 실행 과정과 오류 메시지를 VS Code 터미널에서 함께 보기 편하다.

이 상태에서 breakpoint를 설정하고 F5로 실행하면 평소 터미널에서 서버를 실행하면서 디버거까지 붙인 것과 비슷한 흐름으로 작업할 수 있다.

최소 설정은 네 가지부터 확인한다

ComfyUI용 launch.json을 처음 만든다면 설정을 지나치게 늘리지 않는 편이 좋다.

실제로 적용할 때 체크할 점

type → Python Debugger를 사용하는 debugpy

request → 새 프로세스를 시작하는 launch

program → ComfyUI의 main.py

cwd → 실제 ComfyUI 루트

args → 필요한 경우 --listen, --port 등의 실행 옵션

console → 로그 확인을 위한 integratedTerminal

여기까지 정상적으로 실행되는지 확인한 다음 필요한 환경 변수나 추가 옵션을 붙이는 편이 문제를 찾기 쉽다.

마지막 확인

VS Code launch.json으로 ComfyUI를 디버깅할 때 핵심은 평소 터미널 실행 조건을 그대로 옮기는 것이다. program은 main.py, cwd는 ComfyUI 루트로 맞추고 기존 command-line 옵션이 있다면 args에 넣으면 된다.

설정 후 F5를 눌렀는데 실행되지 않는다면 먼저 Python interpreter와 cwd를 확인하자. 서버가 정상적으로 시작되면 원하는 Python 코드에 breakpoint를 걸고 ComfyUI의 실제 실행 흐름을 따라가며 디버깅하면 된다.