VS Code launch.json 으로 FastAPI 디버깅 환경 구성하기

FastAPI 프로젝트를 개발할 때 VS Code의 디버그 기능을 사용하면 편리하게 서버를 실행하고 디버깅할 수 있습니다.

이번에는 .vscode/launch.json을 설정해 FastAPI 앱을 실행하고, 실행할 때마다 포트를 직접 입력받도록 구성한 내용을 정리합니다.

개요

FastAPI는 보통 uvicorn을 사용해 실행합니다.

예를 들어 터미널에서는 다음과 같이 실행할 수 있습니다.

uvicorn app.main:app --reload --port 8000

하지만 개발 중에는 VS Code의 디버그 실행을 사용하는 경우가 많습니다. 이때 매번 포트를 고정하지 않고, 실행 시점에 직접 입력하고 싶어 VS Code의 inputs 기능을 사용했습니다.

launch.json 설정

.vscode/launch.json 파일에 다음과 같이 설정합니다.

{
  "configurations": [
    {
      "name": "Python 디버거: FastAPI",
      "type": "debugpy",
      "request": "launch",
      "module": "uvicorn",
      "cwd": "${fileDirname}/..",
      "args": [
        "app.main:app",
        "--reload",
        "--port",
        "${input:port}"
      ],
      "justMyCode": true
    }
  ],
  "inputs": [
    {
      "id": "port",
      "type": "promptString",
      "description": "포트를 입력하세요.",
      "default": "8000"
    }
  ]
}

이 설정을 추가한 뒤 VS Code에서 디버그 실행을 하면, 실행 전에 포트를 입력하는 창이 나타납니다.

기본값은 8000으로 설정되어 있으며, 필요에 따라 8001, 8080 등 원하는 포트를 입력해 실행할 수 있습니다.

주요 설정 설명

module

"module": "uvicorn"

program 대신 module을 사용하면 Python 모듈 실행 방식으로 uvicorn을 실행합니다.

터미널에서 다음 명령어를 실행하는 것과 비슷한 방식입니다.

python -m uvicorn app.main:app --reload --port 8000

args

"args": [
  "app.main:app",
  "--reload",
  "--port",
  "${input:port}"
]

args는 uvicorn 실행 시 전달할 인자입니다.

여기서 "app.main:app"은 FastAPI 앱의 위치를 의미합니다.

app.main:app

이는 app/main.py 파일 안에 있는 app 객체를 실행한다는 의미입니다.

예를 들어 FastAPI 앱이 다음과 같이 정의되어 있다면 사용할 수 있습니다.

from fastapi import FastAPI

app = FastAPI()

cwd

"cwd": "${fileDirname}/.."

cwd는 실행 기준 경로를 의미합니다.

상대 경로 문제를 피하기 위해 현재 파일이 있는 디렉터리의 상위 경로를 기준으로 실행하도록 설정했습니다.

프로젝트 구조에 따라 이 값은 달라질 수 있습니다.

예를 들어 프로젝트 루트에서 실행해야 한다면 다음과 같이 설정할 수도 있습니다.

"cwd": "${workspaceFolder}"

프로젝트 구조가 명확하다면 ${workspaceFolder}를 사용하는 편이 더 안정적일 수 있습니다.

inputs

"inputs": [
  {
    "id": "port",
    "type": "promptString",
    "description": "포트를 입력하세요.",
    "default": "8000"
  }
]

inputs는 VS Code의 입력 변수 기능입니다.

id에 지정한 값은 args에서 다음과 같이 참조할 수 있습니다.

"${input:port}"

이렇게 설정하면 디버그 실행 시 VS Code가 사용자에게 입력창을 띄우고, 입력된 값을 실행 인자로 전달합니다.

실행 흐름

설정을 적용한 뒤 실행 흐름은 다음과 같습니다.

1. VS Code에서 FastAPI 디버그 설정을 선택합니다.
2. F5 또는 디버그 실행 버튼을 누릅니다.
3. 포트를 입력하는 창이 표시됩니다.
4. 원하는 포트를 입력합니다.
5. 입력한 포트로 uvicorn이 실행됩니다.

예를 들어 8001을 입력하면 다음과 비슷하게 실행됩니다.

python -m uvicorn app.main:app --reload --port 8001

정리

VS Code의 launch.json에서 inputs를 사용하면 디버그 실행 시 필요한 값을 직접 입력받을 수 있습니다.

FastAPI 실행 포트를 매번 다르게 지정하고 싶을 때 유용하며, 여러 서비스를 동시에 실행하거나 포트 충돌을 피해야 하는 상황에서도 편리합니다.

최종적으로 사용한 핵심 설정은 다음과 같습니다.

"args": [
  "app.main:app",
  "--reload",
  "--port",
  "${input:port}"
]

그리고 입력값은 inputs에서 정의합니다.

{
  "id": "port",
  "type": "promptString",
  "description": "포트를 입력하세요.",
  "default": "8000"
}

이 설정을 통해 VS Code에서 FastAPI를 실행할 때마다 원하는 포트를 입력해 실행할 수 있습니다.