VS Code에서 파이썬 코딩 중인데, 어떤 Framework의 Extension을 개발 중이야. 그런데 코드에서 Framework의 코드를 Reference 하는데 이게 동작 중에는 잘 동작하지만 개발 중에는 Framework의 소스코드는 같이 불러오지 않고 코딩해서 에러처럼 경고가 뜨고 Go to definition 같은 기능도 잘 동작하지 않아. 이를 해결하는 방법 있을까

좋아, 상황 정리하면 “실행 때는 잘 되는데, VS Code에서 개발할 때 프레임워크 모듈을 못 찾아서 경고/Go to Definition이 안 된다”는 거지. 이건 에디터가 쓰는 파이썬 인터프리터/검색 경로와 런타임의 그것이 다르기 때문 이야. 아래 순서대로 하면 거의 항상 해결돼.

1) 에디터가 사용하는 인터프리터에 프레임워크를 설치

  1. 프로젝트용 가상환경을 하나 정하고(또는 새로 만들고) VS Code에서 Python: Select Interpreter 로 그 인터프리터를 선택.

  2. 그 같은 인터프리터(venv)에 프레임워크를 설치.

    • pip: 
      python -m venv .venv
.venv/Scripts/activate  # (Windows)  |  source .venv/bin/activate  # (macOS/Linux)
pip install <framework>  # 필요한 extras가 있으면 <framework>[dev] 처럼
    • Poetry: 
      poetry add -G dev <framework>
poetry env use <파이썬경로>

  3. 이렇게 하면 Pylance/파이썬 확장도 그 venv의 site-packages 를 보게 되어 경고가 사라지고 “Go to Definition”도 동작해.

2) 프레임워크 “소스”로 맞춰 개발해야 한다면 (editable install / 멀티루트)

런타임과 동일한 버전의 소스 를 보고 싶거나, 프레임워크를 로컬에서 같이 수정 중이면:

  • 프레임워크 repo를 옆에 체크아웃해 두고 editable install : 
    pip install -e ../framework-repo  # src 레이아웃이면 -e ../framework-repo[src]
  • 혹은 VS Code 멀티 루트 워크스페이스 로 두 폴더를 함께 열고, Pylance가 경로를 알도록 extraPaths를 지정:
    .vscode/settings.json 
    {
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.analysis.extraPaths": [
    "../framework-repo",          // 패키지 루트
    "../framework-repo/src"       // src 레이아웃일 때
  ],
  "python.analysis.typeCheckingMode": "basic"
}

3) 런타임에서만 sys.path가 바뀌는 프레임워크(플러그인/확장 포인트)일 때

프레임워크가 실행 시점에만 경로를 추가한다면 에디터는 그걸 몰라. 두 가지 중 하나로 맞춰줘:

  • PYTHONPATH 사용 (VS Code가 로드하도록 .env 활용)

    • .vscode/settings.json 
      {
  "python.envFile": "${workspaceFolder}/.env"
}
    • .env 
      PYTHONPATH=../framework-runtime-path:../another/path

  • 혹은 위의 python.analysis.extraPaths로 똑같은 경로를 넣어줘.

4) 타입/정의만 필요할 때(대형/비공개 프레임워크)

실행 가능한 전체 설치가 부담스러우면 stub(.pyi) 만 만들어서 참조해도 “Go to Definition/타입 추론”이 좋아져.

  • Pyright로 스텁 생성: 
    pyright --createstub <framework_pkg_name>

생성된 스텁 폴더를 프로젝트의 typings/에 두고: json { "python.analysis.stubPath": "typings" }

  • mypy의 stubgen을 써도 됨: 
    python -m mypy.stubgen -m <framework_pkg_name> -o typings

5) 도커/원격 런타임에서만 설치되어 있을 때

런타임이 Docker/원격(SSH)라면 Dev Containers 또는 Remote - SSH 확장으로 “코딩도 그 환경에서” 하게 만드는 게 제일 깔끔해. 그러면 에디터가 보는 인터프리터 == 런타임 인터프리터가 되어 경로 문제 자체가 사라짐.

6) 추가 팁 (자잘하지만 유용)

  • 경고만 잠깐 숨기려면(원인 해결 전 임시):

    • 파일 상단에 # pyright: reportMissingImports=false (혹은 해당 import 줄에 # type: ignore[import])
      → 근본 해결은 아님.

  • 네임스페이스 패키지(PEP 420)나 src/ 레이아웃이면 패키지 루트 가 맞게 잡혔는지 확인.

  • 동적 속성/컴파일드 모듈이라 정의 점프가 어려우면:

    from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from framework import FancyAPI  # 에디터용 힌트

가장 빠른 체크리스트

  1. VS Code에서 Python Interpreter 가 내가 쓰는 venv로 맞나?

  2. 그 venv에 프레임워크가 설치 되어 있나(또는 pip install -e로 연결했나)?

  3. 소스 트리라면 python.analysis.extraPaths/PYTHONPATH가 프레임워크 루트를 가리키나?

  4. 특별한 경우엔 stub 생성해서 stubPath 설정.

원하시면 현재 프로젝트 구조(폴더 레이아웃/가상환경/설치 방식) 알려줘. 거기에 맞춘 settings.json / .env / 설치 커맨드 를 딱 맞게 써줄게.

Categories:

Updated:

You may also enjoy