Visual Studio의 Linux에서 Python 코드 원격 디버그

아티클
02/05/2025

이 문서에서는 원격 Linux 컴퓨터에서 Python 코드 디버깅을 지원하도록 Visual Studio 설치를 구성하는 방법을 알아보세요. 이 연습은 Visual Studio 2019 버전 16.6을 기반으로 합니다.

Visual Studio는 Windows 컴퓨터에서 로컬 및 원격으로 Python 애플리케이션을 시작하고 디버그할 수 있습니다. 또한 Visual Studio는 debugpy 라이브러리사용하여 CPython 이외의 다른 운영 체제, 디바이스 또는 Python 구현에서 원격으로 디버깅을 지원합니다.

Visual Studio 2019 버전 16.4 이하에서는 ptvsd 라이브러리사용합니다. Visual Studio 2019 버전 16.5 이상에서는 디버그 라이브러리가 ptvsd를 대체합니다. debugpy를 사용하면 디버그 중인 Python 코드가 Visual Studio에서 연결할 수 있는 디버그 서버를 호스트합니다. 이 호스팅을 수행하려면 서버를 가져오고 사용하도록 설정하기 위해 코드를 약간 수정해야 합니다. TCP 연결을 허용하도록 원격 컴퓨터에서 네트워크 또는 방화벽 구성을 조정해야 할 수도 있습니다.

필수 구성 요소

Python 워크로드를 지원하는 Visual Studio가 설치되었습니다. 자세한 내용은 Visual Studio에서 Python 설치 지원을 하는 방법에 대해참조하세요.
macOS 또는 Linux와 같은 운영 체제에서 Python을 실행하는 원격 컴퓨터입니다.
원격 컴퓨터의 방화벽에서 포트 5678(인바운드)이 열리며 이는 원격 디버깅의 기본값입니다.

Linux 컴퓨터 설정

Azure 에서 Linux 가상 머신을 쉽게 만들 수 있으며, Windows의 원격 데스크톱 를 사용하여에 액세스할 수 있습니다. Python은 기본적으로 설치되므로 가상 머신에 대한 Ubuntu는 편리합니다. 구성이 다르다면 기타 Python 다운로드 위치를 위해 Python 인터프리터 설치을 참조하세요.

방화벽 구성

원격 디버깅을 지원하려면 원격 컴퓨터의 방화벽에서 인바운드 포트 5678을 열어야 합니다.

Azure 가상 머신에 대한 방화벽 규칙을 만드는 방법에 대한 자세한 내용은 다음 문서를 참조하세요.

Azure Portal 사용하여 네트워크 보안 그룹으로 네트워크 트래픽 필터링
Azure Portal을 사용하여 경로 테이블로 네트워크 트래픽을 라우팅
Azure Portal 사용하여 Azure Firewall 배포 및 구성

디버깅을 위한 스크립트 준비

다음 단계에 따라 Linux에서 Python 코드를 디버깅하기 위한 스크립트를 준비합니다.

원격 컴퓨터에서 다음 코드를 사용하여 guessing-game.py이라는 Python 파일을 만듭니다.

import random

guesses_made = 0
name = input('Hello! What is your name?\n')
number = random.randint(1, 20)
print('Well, {0}, I am thinking of a number between 1 and 20.'.format(name))

while guesses_made < 6:
    guess = int(input('Take a guess: '))
    guesses_made += 1
    if guess < number:
        print('Your guess is too low.')
    if guess > number:
        print('Your guess is too high.')
    if guess == number:
        break
if guess == number:
    print('Good job, {0}! You guessed my number in {1} guesses!'.format(name, guesses_made))
else:
    print('Nope. The number I was thinking of was {0}'.format(number))

pip3 install debugpy 명령을 사용하여 환경에 debugpy 패키지를 설치합니다.

메모

문제 해결에 필요한 경우에 대비하여 설치된 debugpy 버전을 기록하는 것이 좋습니다. 디버그 목록 사용 가능한 버전도 표시됩니다.
다른 코드 앞에 guessing-game.py 파일 맨 위에 다음 코드를 추가하여 원격 디버깅을 사용하도록 설정합니다. (엄격한 요구 사항은 아니지만 listen 함수가 호출되기 전에 생성된 백그라운드 스레드를 디버그하는 것은 불가능합니다.)
```
import debugpy
debugpy.listen(('0.0.0.0', 5678))
```
파일을 저장하고 프로그램을 실행합니다.
```
python3 guessing-game.py
```
listen 함수에 대한 호출은 백그라운드에서 실행되며 프로그램과 상호 작용할 때 들어오는 연결을 기다립니다. 원하는 경우 디버거가 연결될 때까지 listen 함수를 호출하여 프로그램을 차단한 후 wait_for_client 함수를 호출할 수 있습니다.

팁

debugpy는 listen 및 wait_for_client 함수 외에도 도우미 함수 breakpoint제공합니다. 이 함수는 디버거가 연결된 경우 프로그래밍 방식 중단점 역할을 합니다. is_client_connected1또 다른 함수는 디버거가 연결된 경우 True 반환합니다. 다른 debugpy 함수를 호출하기 전에 이 결과를 확인할 필요가 없습니다.

Python 도구에서 원격으로 연결

다음 단계에서는 중단점을 설정하여 원격 프로세스를 중지하는 방법을 보여줍니다.

로컬 컴퓨터에서 원격 파일의 복사본을 만들고 Visual Studio에서 엽니다. 파일의 위치는 중요하지 않지만 해당 이름은 원격 컴퓨터의 스크립트 이름과 일치해야 합니다.
(선택 사항) 로컬 컴퓨터에 디버그피용 IntelliSense를 사용하려면 Python 환경에 디버그피 패키지를 설치합니다.
디버그>프로세스에 연결을 선택합니다.
프로세스에 연결 대화 상자에서 연결 형식을 Python 원격(debugpy)로 설정합니다.
연결 대상 필드에 명령 tcp://<ip_address>:5678입력합니다.
- tcp:// 연결 형식을 TCP(Transmission Control Protocol)로 지정합니다.
- <ip_address> 원격 컴퓨터의 IP 주소이며 명시적 주소 또는 myvm.cloudapp.net같은 이름이 될 수 있습니다.
- :5678 원격 디버깅 포트 번호입니다.
입력을 선택하여 해당 컴퓨터에서 사용 가능한 디버그피 프로세스 목록을 채웁다.

목록을 채운 후 원격 컴퓨터에서 다른 프로그램을 시작한 경우 새로 고침 버튼을 선택합니다.
디버그할 프로세스를 선택하고 부착을 선택하거나, 프로세스를 두 번 클릭합니다.
스크립트가 원격 컴퓨터에서 계속 실행되는 동안 Visual Studio가 디버깅 모드로 전환되며, 일반적인 디버깅 기능을 모두 제공합니다.

if guess < number: 줄에 중단점을 설정한 다음 원격 컴퓨터로 전환하고 다른 추측을 입력할 수 있습니다. 로컬 컴퓨터의 Visual Studio가 중단점에서 중지되고, 지역 변수가 표시되며, 다음과 같은 작업이 수행됩니다.

중단점이 적중되면 Visual Studio에서 디버깅을 일시 중지하는 방법을 보여 주는
디버깅을 중지하면 Visual Studio가 프로그램에서 분리됩니다. 프로그램은 원격 컴퓨터에서 계속 실행됩니다. 또한 debugpy는 디버거 연결에 대한 수신 대기를 계속하므로 언제든지 프로세스에 다시 연결할 수 있습니다.

연결 문제 해결

연결 관련 문제를 해결하려면 다음 사항을 검토하세요.

Python 원격(디버그피)를 연결 유형으로선택해야 합니다.
연결 대상 비밀이 원격 코드의 비밀과 정확히 일치하는지 확인합니다.
연결 대상 IP 주소가 원격 컴퓨터의 IP 주소와 일치하는지 확인합니다.
원격 컴퓨터의 원격 디버깅 포트가 열려 있고 연결 대상에 :5678같은 포트 접미사가 포함되어 있는지 확인합니다.

다른 포트를 사용하려면 debugpy.listen((host, port))것처럼 listen 함수 호출에서 포트 번호를 지정합니다. 이 경우 방화벽에서 특정 포트를 열어야 합니다.
원격 컴퓨터에 설치된 디버그피 버전(pip3 list 명령에서 반환됨)이 Visual Studio Python 도구(PTVS) 버전과 일치하는지 확인합니다.

다음 표에서는 유효한 버전 쌍을 나열합니다. 필요에 따라 원격 컴퓨터에서 debugpy 버전을 업데이트합니다.

Visual Studio Python 도구 debugpy

2019 16.6 1.0.0b5 1.0.0b5

2019 16.5 1.0.0b1 1.0.0b1

Visual Studio	Python 도구	debugpy
2019 16.6	1.0.0b5	1.0.0b5
2019 16.5	1.0.0b1	1.0.0b1

메모

Visual Studio 2019 버전 16.0-16.4에서는 debugpy가 아닌 ptvsd를 사용했습니다. 해당 버전에 대한 이 연습의 프로세스는 비슷하지만 함수 이름은 다릅니다. Visual Studio 2019 버전 16.5는 debugpy를 사용하지만 함수 이름은 ptvsd의 이름과 동일합니다. listen대신 enable_attach사용합니다. wait_for_client대신 wait_for_attach사용합니다. breakpoint대신 break_into_debugger사용합니다.

레거시 디버깅에 ptvsd 3.x 사용

ptvsd 3.x 레거시 디버거는 Visual Studio 2017 버전 15.7 이하의 기본값입니다.

Visual Studio 구성에 따라 원격 디버깅에 ptvsd 3.x를 사용해야 할 수 있습니다.

Python 2.6, 3.1~3.4 또는 IronPython을 사용한 Visual Studio 2017 버전 15.7 이하
Python 2.6, 3.1~3.4 또는 IronPython을 사용한 Visual Studio 2019 버전 16.5 이상
초기 4.x 버전

구성에서 이전 버전 시나리오를 구현하는 경우 Visual Studio에서 오류를 표시합니다. 디버거는 이 Python 환경지원하지 않습니다.

원격 디버깅 설정

ptvsd 3.x를 사용하여 원격 디버깅을 준비하려면 다음 단계를 완료합니다.

실행 중인 스크립트에 대한 액세스를 제한하는 데 사용되는 비밀을 설정합니다.

ptvsd 3.x에서 enable_attach 함수를 사용하려면 첫 번째 인수로 "secret"을 전달해야 합니다.
- 원격 디버거를 연결할 때 enable_attach(secret="<secret>") 명령을 사용하여 비밀을 입력합니다.
enable_attach(secret=None) 명령을 사용하여 누구나 연결할 수 있지만 이 옵션은 권장되지 않습니다.
tcp://<secret>@<ip_address>:5678양식에서 연결 대상 URL을 만듭니다.
- tcp:// 연결 형식을 TCP로 지정합니다.
- <secret> Python 코드의 enable_attach 함수와 함께 전달되는 문자열입니다.
- <ip_address> 원격 컴퓨터의 IP 주소이며 명시적 주소 또는 myvm.cloudapp.net같은 이름이 될 수 있습니다.
- :5678 원격 디버깅 포트 번호입니다.

TCPS 프로토콜을 사용하여 보안 연결

기본적으로 ptvsd 3.x 원격 디버그 서버에 대한 연결은 비밀로만 보호되며 모든 데이터는 일반 텍스트로 전달됩니다. 더 안전한 연결을 위해 ptvsd 3.x는 TCP 프로토콜의 보안 형식을 사용하거나 TCPS SSL을 지원합니다.

TCPS 프로토콜을 사용하도록 ptvsd 3.x를 구성하려면 다음 단계를 사용합니다.

원격 컴퓨터에서 openssl 명령을 사용하여 키와 자체 서명된 인증서에 대한 별도의 파일을 생성합니다.
```
openssl req -new -x509 -days 365 -nodes -out cert.cer -keyout cert.key
```
- openssl 프롬프트에서 일반 이름연결하는 데 사용하는 호스트 이름 또는 IP 주소를 입력합니다.
자세한 내용은 Python ssl 모듈 설명서에서 자체 서명된 인증서를 참조하세요. Python 설명서에 설명된 명령은 결합된 단일 파일만 생성합니다.
코드에서 파일 이름을 값으로 사용하여 certfile 및 keyfile 인수를 포함하도록 enable_attach 함수에 대한 호출을 수정합니다. 이러한 인수는 표준 ssl.wrap_socket Python 함수와 동일한 의미를 갖습니다.
```
ptvsd.enable_attach(secret='my_secret', certfile='cert.cer', keyfile='cert.key')
```
로컬 컴퓨터의 코드 파일에서도 동일한 변경 작업을 수행할 수 있습니다. 이 코드는 실제로 실행되지 않으므로 반드시 필요한 것은 아닙니다.
디버깅할 준비가 되도록 원격 컴퓨터에서 Python 프로그램을 다시 시작합니다.
Visual Studio를 사용하여 Windows 컴퓨터의 신뢰할 수 있는 루트 CA에 인증서를 추가하여 채널을 보호합니다.
1. 원격 컴퓨터에서 로컬 컴퓨터로 인증서 파일을 복사합니다.
2. 제어판 열고 Windows Tools>컴퓨터 인증서관리로 이동합니다.
3. 인증서 [인증서 - 로컬 컴퓨터] 대화 상자에서 신뢰할 수 있는 루트 인증 기관 노드를 확장하고, 인증서를 마우스 오른쪽 버튼으로 클릭한 후, 모든 작업을 선택한 다음,가져오기>를 선택합니다.
4. 원격 컴퓨터에서 복사한 .cer 파일을 찾아 선택합니다.
5. 대화 상자 프롬프트를 계속 진행하여 가져오기 프로세스를 완료합니다.
Python 도구 원격으로 연결하기앞에서 설명한 대로 Visual Studio에서 연결 프로세스를 반복합니다.

이 인스턴스의 경우 tcps://연결 대상(또는 한정자)에 대한 프로토콜로 정의합니다.

연결 문제 해결

연결 시도 중에 Visual Studio에 문제가 발생할 수 있습니다. 다음 시나리오를 검토하고 필요에 따라 적절한 조치를 취합니다.

Visual Studio는 SSL을 통해 연결할 때 잠재적인 인증서 문제에 대해 경고합니다.

작업: 메시지를 무시하고 계속 진행할 수 있습니다.

주의

채널은 여전히 도청에 대해 암호화되어 있지만 중간에서 맨 인 더 미들 공격에 열려 있을 수 있습니다.
Visual Studio는 원격 인증서가 신뢰되지 않는다는 경고를 표시합니다.

문제: 인증서가 신뢰할 수 있는 루트 CA에 제대로 추가되지 않았습니다.

작업: Windows 컴퓨터 신뢰할 수 있는 루트 CA에 인증서를 추가단계를 다시 확인하고 연결을 다시 시도합니다.
Visual Studio는 원격 인증서 이름이 호스트 이름 경고와 일치하지 않음을 표시합니다.

문제: 인증서의 일반 이름 적절한 호스트 이름 또는 IP 주소가 지정되지 않았습니다.

작업: TCPS연결을 안전하게 하는 단계를 다시 확인합니다. 인증서를 만들 때 올바른 일반 이름 사용하고 연결을 다시 시도해야 합니다.

원격 디버깅

다음을 통해 공유

Visual Studio의 Linux에서 Python 코드 원격 디버그

필수 구성 요소