Linux에서 Python 코드 원격 디버그Remotely debug Python code on Linux

Visual Studio는 Windows 컴퓨터에서 Python 애플리케이션을 로컬 및 원격으로 시작하고 디버그할 수 있습니다(Remote Debugging(원격 디버깅) 참조).Visual Studio can launch and debug Python applications locally and remotely on a Windows computer (see Remote debugging). 또한 ptvsd 라이브러리를 사용하여 CPython 이외의 다른 운영 체제, 디바이스 또는 Python 구현에서 원격으로 디버그할 수도 있습니다.It can also debug remotely on a different operating system, device, or Python implementation other than CPython using the ptvsd library.

ptvsd를 사용하는 경우 디버그되는 Python 코드는 Visual Studio에서 연결할 수 있는 디버그 서버를 호스팅합니다.When using ptvsd, the Python code being debugged hosts the debug server to which Visual Studio can attach. 이 호스팅을 사용하려면 서버를 가져오고 사용할 수 있도록 코드를 약간 수정해야 하며, TCP 연결을 허용하기 위해 원격 컴퓨터에 네트워크 또는 방화벽 구성이 필요할 수 있습니다.This hosting requires a small modification to your code to import and enable the server, and may require network or firewall configurations on the remote computer to allow TCP connections.

동영상에 대한 비디오 카메라 아이콘movie camera icon for video 원격 디버깅에 대한 소개는 심층 분석: (Visual Studio 2015 및 2017에 모두 적용되는) 플랫폼 간 원격 디버깅(youtube.com, 6분 22초)을 참조하세요.For an introduction to remote debugging, see Deep Dive: Cross-platform remote debugging (youtube.com, 6m22s), which is applicable to both Visual Studio 2015 and 2017.

Linux 컴퓨터 설정Set up a Linux computer

이 연습을 수행하려면 다음 항목이 필요합니다.The following items are needed to follow this walkthrough:

  • Mac OSX 또는 Linux와 같은 운영 체제에서 Python을 실행하는 원격 컴퓨터.A remote computer running Python on an operating system like Mac OSX or Linux.
  • 원격 디버깅의 기본값으로 해당 컴퓨터의 방화벽에서 열려 있는 포트 5678(인바운드).Port 5678 (inbound) opened on that computer's firewall, which is the default for remote debugging.

쉽게 Azure에서 Linux 가상 머신을 만들고 Windows에서 원격 데스크톱을 사용하여 Linux 가상 머신에 액세스할 수 있습니다.You can easily create a Linux virtual machine on Azure and access it using Remote Desktop from Windows. Python이 기본적으로 설치되어 있으므로 VM에 Ubuntu를 사용하면 편리합니다. 그렇지 않은 경우 추가 Python 다운로드 위치는 원하는 Python 인터프리터 설치를 참조하세요.Ubuntu for the VM is convenient because Python is installed by default; otherwise, see the list on Install a Python interpreter of your choice for additional Python download locations.

Azure VM에 대한 방화벽 규칙을 만드는 방법에 대한 자세한 내용은 Azure Portal을 사용하여 Azure에서 VM으로 포트 열기를 참조하세요.For details on creating a firewall rule for an Azure VM, see Open ports to a VM in Azure using the Azure portal.

디버그할 스크립트 준비Prepare the script for debugging

  1. 원격 컴퓨터에서 다음 코드를 사용하여 guessing-game.py라는 Python 파일을 만듭니다.On the remote computer, create a Python file called guessing-game.py with the following code:

    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))
    
  2. pip3 install ptvsd를 사용하여 사용자 환경에 ptvsd 패키지를 설치합니다.Install the ptvsd package into your environment using pip3 install ptvsd.

    참고

    문제 해결에 필요한 경우를 대비하여 ptvsd 버전을 기록해 두는 것이 좋습니다. ptvsd 목록은 사용 가능한 버전도 보여줍니다.It's a good idea to record the version of ptvsd that's installed in case you need it for troubleshooting; the ptvsd listing also shows available versions.

  3. guessing-game.py에서 가능한 가장 빠른 지점에 다른 코드보다 먼저 해당 코드를 추가하여 원격 디버깅을 사용하도록 설정합니다.Enable remote debugging by adding the code below at the earliest possible point in guessing-game.py, before other code. (엄격한 요구 사항은 아니지만, enable_attach 함수를 호출하기 전에 생성된 모든 백그라운드 스레드를 디버그할 수는 없습니다.)(Though not a strict requirement, it's impossible to debug any background threads spawned before the enable_attach function is called.)

    import ptvsd
    ptvsd.enable_attach()
    
  4. 파일을 저장하고 python3 guessing-game.py를 실행합니다.Save the file and run python3 guessing-game.py. enable_attach에 대한 호출이 백그라운드에서 실행되고, 달리 프로그램과 상호 작용하지 않으면 들어오는 연결을 기다립니다.The call to enable_attach runs in the background and waits for incoming connections as you otherwise interact with the program. 원하는 경우 디버거가 연결될 때까지 enable_attach 뒤에 wait_for_attach 함수를 호출하여 프로그램을 차단할 수 있습니다.If desired, the wait_for_attach function can be called after enable_attach to block the program until the debugger attaches.

enable_attachwait_for_attach 외에도, ptvsd는 디버거가 연결되어 있으면 중단점을 프로그래밍 방식으로 작동하는 break_into_debugger 도우미 함수를 제공합니다.In addition to enable_attach and wait_for_attach, ptvsd also provides a helper function break_into_debugger, which serves as a programmatic breakpoint if the debugger is attached. 또한 디버거가 연결되어 있으면 True를 반환하는 is_attached 함수도 있지만, 다른 ptvsd 함수를 호출하기 전에 이 결과를 확인할 필요가 없습니다.There is also an is_attached function that returns True if the debugger is attached (note that there is no need to check this result before calling any other ptvsd functions).

Python 도구에서 원격으로 연결Attach remotely from Python Tools

이 단계에서는 간단한 중단점을 설정하여 원격 프로세스를 중지합니다.In these steps, we set a simple breakpoint to stop the remote process.

  1. 로컬 컴퓨터에 원격 파일의 복사본을 만들고 Visual Studio에서 엽니다.Create a copy of the remote file on the local computer and open it in Visual Studio. 파일의 위치는 중요하지 않지만, 이름은 원격 컴퓨터의 스크립트 이름과 일치해야 합니다.It doesn't matter where the file is located, but its name should match the name of the script on the remote computer.

  2. (선택 사항) 로컬 컴퓨터에서 ptvsd에 IntelliSense를 사용하려면 Python 환경에 ptvsd 패키지를 설치합니다.(Optional) To have IntelliSense for ptvsd on your local computer, install the ptvsd package into your Python environment.

  3. 디버그 > 프로세스에 연결을 선택합니다.Select Debug > Attach to Process.

  4. 나타나는 프로세스에 연결 대화 상자에서 연결 형식Python remote (ptvsd) (Python 원격(ptvsd))로 설정합니다.In the Attach to Process dialog that appears, set Connection Type to Python remote (ptvsd). (이전 버전의 Visual Studio에서는 명령 이름이 전송Python 원격 디버깅이었습니다.)(On older versions of Visual Studio these commands are named Transport and Python remote debugging.)

  5. 연결 대상 필드(이전 버전의 경우 한정자)에 tcp://<ip_address>:5678을 입력합니다. 여기서 <ip_address>는 원격 컴퓨터의 IP 주소이고(명시적 주소 또는 myvm.cloudapp.net과 같은 이름일 수 있음), :5678은 원격 디버깅 포트 번호입니다.In the Connection Target field (Qualifier on older versions), enter tcp://<ip_address>:5678 where <ip_address> is that of the remote computer (which can be either an explicit address or a name like myvm.cloudapp.net), and :5678 is the remote debugging port number.

  6. Enter 키를 눌러 해당 컴퓨터에서 사용할 수 있는 ptvsd 프로세스의 목록을 채웁니다.Press Enter to populate the list of available ptvsd processes on that computer:

    연결 대상 입력 및 프로세스 나열

    이 목록을 채운 후 원격 컴퓨터에서 다른 프로그램을 시작하게 되는 경우 새로 고침 단추를 선택합니다.If you happen to start another program on the remote computer after populating this list, select the Refresh button.

  7. 디버그할 프로세스를 선택한 다음 연결을 선택하거나 프로세스를 두 번 클릭합니다.Select the process to debug and then Attach, or double-click the process.

  8. 그러면 스크립트가 원격 컴퓨터에서 계속 실행되는 동안 Visual Studio에서 디버깅 모드로 전환하여 모든 일반적인 디버깅 기능을 제공합니다.Visual Studio then switches into debugging mode while the script continues to run on the remote computer, providing all the usual debugging capabilities. 예를 들어 if guess < number: 줄에 중단점을 설정한 다음 원격 컴퓨터로 전환하고 다른 guess를 입력합니다.For example, set a breakpoint on the if guess < number: line, then switch over to the remote computer and enter another guess. 이렇게 하고 나면 로컬 컴퓨터의 Visual Studio가 해당 중단점에서 중지하고 로컬 변수 등을 보여 줍니다.After you do so, Visual Studio on your local computer stops at that breakpoint, shows local variables, and so on:

    Visual Studio에서 중단점이 적중될 때 디버깅 일시 중지

  9. 디버깅을 중지하면 Visual Studio는 원격 컴퓨터에서 계속 실행되는 프로그램에서 분리됩니다.When you stop debugging, Visual Studio detaches from the program, which continues to run on the remote computer. 또한 ptvsd는 계속 디버거 연결을 수신 대기하므로 언제든지 프로세스에 다시 연결할 수 있습니다.ptvsd also continues listening for attaching debuggers, so you can reattach to the process again at any time.

연결 문제 해결Connection troubleshooting

  1. 연결 형식에 대해 Python remote (ptvsd) (Python 원격(ptvsd))를 선택했는지 확인합니다(이전 버전의 경우 전송에 대해 Python 원격 디버깅).Make sure that you've selected Python remote (ptvsd) for the Connection Type (Python remote debugging for Transport with older versions.)

  2. 연결 대상(또는 한정자)의 암호가 원격 코드의 암호와 정확히 일치하는지 확인합니다.Check that the secret in the Connection Target (or Qualifier) exactly matches the secret in the remote code.

  3. 연결 대상(또는 한정자)의 IP 주소가 원격 컴퓨터의 IP 주소와 일치하는지 확인합니다.Check that the IP address in the Connection Target (or Qualifier) matches that of the remote computer.

  4. 원격 컴퓨터에서 원격 디버깅 포트를 열었는지와 연결 대상에 :5678과 같은 포트 접미사를 포함했는지 확인합니다.Check that you're opened the remote debugging port on the remote computer, and that you've included the port suffix in the connection target, such as :5678.

    • 다른 포트를 사용해야 하는 경우 ptvsd.enable_attach(address = ('0.0.0.0', 8080))에서처럼 enable_attach 호출에서 address 인수를 사용하여 지정할 수 있습니다.If you need to use a different port, you can specify it in the enable_attach call using the address argument, as in ptvsd.enable_attach(address = ('0.0.0.0', 8080)). 이 경우 방화벽에서 해당 특정 포트를 엽니다.In this case, open that specific port in the firewall.
  5. pip3 list로 반환된, 원격 컴퓨터에 설치된 ptvsd 버전이 Visual Studio에서 사용 중인 Python 도구 버전에서 사용되는 ptvsd 버전과 일치하는지 아래 표에서 확인합니다.Check that the version of ptvsd installed on the remote computer as returned by pip3 list matches that used by the version of the Python tools you're using in Visual Studio in the table below. 필요한 경우 원격 컴퓨터에서 ptvsd를 업데이트합니다.If necessary, update ptvsd on the remote computer.

    Visual Studio 버전Visual Studio version Python 도구/ptvsd 버전Python tools/ptvsd version
    2017 15.82017 15.8 4.1.1a9(레거시 디버거: 3.2.1.0)4.1.1a9 (legacy debugger: 3.2.1.0)
    2017 15.72017 15.7 4.1.1a1(레거시 디버거: 3.2.1.0)4.1.1a1 (legacy debugger: 3.2.1.0)
    2017 15.4, 15.5, 15.62017 15.4, 15.5, 15.6 3.2.1.03.2.1.0
    2017 15.32017 15.3 3.2.03.2.0
    2017 15.22017 15.2 3.1.03.1.0
    2017 15.0, 15.12017 15.0, 15.1 3.0.03.0.0
    20152015 2.2.62.2.6
    20132013 2.2.22.2.2
    2012, 20102012, 2010 2.12.1

ptvsd 3.x 사용Using ptvsd 3.x

다음 정보는 ptvsd 4.x에서 제거된 특정 기능을 포함하는 ptvsd 3.x를 사용한 원격 디버깅에만 적용됩니다.The following information applies only to remote debugging with ptvsd 3.x, which contains certain features that were removed in ptvsd 4.x.

  1. ptvsd 3.x에서 enable_attach 함수를 사용하려면 실행 중인 스크립트에 대한 액세스를 제한하는 첫 번째 인수로 “secret”을 전달해야 했습니다.With ptvsd 3.x, the enable_attach function required that you pass a "secret" as the first argument that restricts access to the running script. 원격 디버거를 연결할 때 이 비밀을 입력합니다.You enter this secret when attaching the remote debugger. (권장되지는 않지만, enable_attach(secret=None)를 사용하여 모든 사용자의 연결을 허용할 수 있습니다.)Though not recommended, you can allow anyone to connect, use enable_attach(secret=None).

  2. 연결 대상 URL은 tcp://<secret>@<ip_address>:5678입니다. 여기서 <secret>은 Python 코드의 enable_attach에 전달된 문자열입니다.The connection target URL is tcp://<secret>@<ip_address>:5678 where <secret> is the string passed enable_attach in the Python code.

기본적으로 ptvsd 3.x 원격 디버그 서버에 대한 연결은 비밀로만 보호되고 모든 데이터는 일반 텍스트로 전달됩니다.By default, the connection to the ptvsd 3.x remote debug server is secured only by the secret and all data is passed in plain text. 보다 안전한 연결을 위해 ptvsd 3.x에서는 다음과 같이 설정하는 tcsp 프로토콜을 사용하여 SSL을 지원합니다.For a more secure connection, ptvsd 3.x supports SSL using the tcsp protocol, which you set up as follows:

  1. 원격 컴퓨터에서 다음과 같이 openssl을 사용하여 별도의 자체 서명된 인증서 및 키 파일을 생성합니다.On the remote computer, generate separate self-signed certificate and key files using openssl:

    openssl req -new -x509 -days 365 -nodes -out cert.cer -keyout cert.key
    

    openssl에서 메시지를 표시하면 일반 이름에 대해 호스트 이름 또는 IP 주소(어느 쪽이든 연결에 사용하는 항목)를 사용합니다.When prompted, use the hostname or IP address (whichever you use to connect) for the Common Name when prompted by openssl.

    (자세한 내용은 Python ssl 모듈 문서의 Self-signed certificates(자체 서명된 인증서)를 참조하세요.(See Self-signed certificates in the Python ssl module docs for additional details. 해당 문서의 명령은 결합된 단일 파일만 생성합니다.)Note that the command in those docs generates only a single combined file.)

  2. 코드에서 파일 이름을 값으로 사용하는 certfilekeyfile 인수를 포함하도록 enable_attach에 대한 호출을 수정합니다(이러한 인수는 표준 ssl.wrap_socket Python 함수에 대해 같은 의미를 지님).In the code, modify the call to enable_attach to include certfile and keyfile arguments using the filenames as the values (these arguments have the same meaning as for the standard ssl.wrap_socket Python function):

    ptvsd.enable_attach(secret='my_secret', certfile='cert.cer', keyfile='cert.key')
    

    로컬 컴퓨터의 코드 파일에서도 같은 변경을 수행할 수 있지만, 이 코드는 실제로 실행되지 않으므로 필요 없습니다.You can also make the same change in the code file on the local computer, but because this code isn't actually run, it isn't strictly necessary.

  3. 원격 컴퓨터에서 Python 프로그램을 다시 시작하여 디버깅을 준비합니다.Restart the Python program on the remote computer, making it ready for debugging.

  4. Visual Studio가 설치된 Windows 컴퓨터에서 신뢰할 수 있는 루트 CA에 인증서를 추가하여 채널을 보호합니다.Secure the channel by adding the certificate to Trusted Root CA on the Windows computer with Visual Studio:

    1. 로원격 컴퓨터의 인증서 파일을 로컬 컴퓨터에 복사합니다.Copy the certificate file from the remote computer to the local computer.
    2. 제어판을 열고 관리 도구 > 컴퓨터 인증서 관리로 이동합니다.Open Control Panel and navigate to Administrative Tools > Manage computer certificates.
    3. 나타나는 창의 왼쪽에서 신뢰할 수 있는 루트 인증 기관을 확장하고, 인증서를 마우스 오른쪽 단추로 클릭하고, 모든 작업 > 가져오기를 선택합니다.In the window that appears, expand Trusted Root Certification Authorities on the left side, right-click Certificates, and select All Tasks > Import.
    4. 원격 컴퓨터에서 복사한 .cer 파일로 이동하여 이 파일을 선택한 다음, 대화 상자를 클릭하여 가져오기를 완료합니다.Navigate to and select the .cer file copied from the remote computer, then click through the dialogs to complete the import.
  5. 앞에서 설명한 대로 Visual Studio에서 연결 프로세스를 반복하고 이제 연결 대상(또는 한정자)에 대한 프로토콜로 tcps://를 사용합니다.Repeat the attach process in Visual Studio as described earlier, now using tcps:// as the protocol for the Connection Target (or Qualifier).

    SSL로 원격 디버깅 전송 선택

  6. SSL을 통해 연결하면 Visual Studio에서 잠재적인 인증서 문제에 대한 메시지를 표시합니다.Visual Studio prompts you about potential certificate issues when connecting over SSL. 경고를 무시하고 계속할 수 있지만, 채널이 여전히 도청으로부터 암호화되더라도 메시지 가로채기(man-in-the-middle) 공격에 개방될 수 있습니다.You may ignore the warnings and proceed, but although the channel is still encrypted against eavesdropping it can be open to man-in-the-middle attacks.

    1. 아래의 원격 인증서를 신뢰할 수 없습니다. 경고가 표시되는 경우 신뢰할 수 있는 루트 CA에 인증서를 제대로 추가하지 않았음을 의미합니다.If you see the remote certificate is not trusted warning below, it means you did not properly add the certificate to the Trusted Root CA. 해당 단계를 확인하고 다시 시도합니다.Check those steps and try again.

      SSL 인증서를 신뢰할 수 있습니다. 경고

    2. 아래의 원격 인증서 이름이 호스트 이름과 일치하지 않습니다. 경고가 표시되는 경우 인증서를 만들 때 일반 이름으로 올바른 호스트 이름 또는 IP 주소를 사용하지 않았음을 의미합니다.If you see the remote certificate name does not match hostname warning below, it means you did not use the proper hostname or IP address as the Common Name when creating the certificate.

      SSL 인증서 호스트 이름 경고

Visual Studio는 Windows 컴퓨터에서 Python 애플리케이션을 로컬 및 원격으로 시작하고 디버그할 수 있습니다(Remote Debugging(원격 디버깅) 참조).Visual Studio can launch and debug Python applications locally and remotely on a Windows computer (see Remote debugging). 또한 debugpy 라이브러리를 사용하여 CPython 이외의 다른 운영 체제, 디바이스 또는 Python 구현에서 원격으로 디버그할 수도 있습니다.It can also debug remotely on a different operating system, device, or Python implementation other than CPython using the debugpy library.

debugpy를 사용하는 경우 디버그되는 Python 코드는 Visual Studio에서 연결할 수 있는 디버그 서버를 호스팅합니다.When using debugpy, the Python code being debugged hosts the debug server to which Visual Studio can attach. 이 호스팅을 사용하려면 서버를 가져오고 사용할 수 있도록 코드를 약간 수정해야 하며, TCP 연결을 허용하기 위해 원격 컴퓨터에 네트워크 또는 방화벽 구성이 필요할 수 있습니다.This hosting requires a small modification to your code to import and enable the server, and may require network or firewall configurations on the remote computer to allow TCP connections.

참고

Visual Studio 2019 버전 16.4 및 이전에는 ptvsd 라이브러리가 사용되었습니다.For Visual Studio 2019 version 16.4 and earlier, the ptvsd library was used. debugpy 라이브러리는 Visual Studio 2019 버전 16.5에서 ptvsd 4를 대체했습니다.The debugpy library replaced ptvsd 4 in Visual Studio 2019 version 16.5.

Linux 컴퓨터 설정Set up a Linux computer

이 연습을 수행하려면 다음 항목이 필요합니다.The following items are needed to follow this walkthrough:

  • Mac OSX 또는 Linux와 같은 운영 체제에서 Python을 실행하는 원격 컴퓨터.A remote computer running Python on an operating system like Mac OSX or Linux.
  • 원격 디버깅의 기본값으로 해당 컴퓨터의 방화벽에서 열려 있는 포트 5678(인바운드).Port 5678 (inbound) opened on that computer's firewall, which is the default for remote debugging.

참고

이 연습은 Visual Studio 2019 버전 16.6을 기반으로 합니다.This walkthrough is based on Visual Studio 2019 version 16.6.

쉽게 Azure에서 Linux 가상 머신을 만들고 Windows에서 원격 데스크톱을 사용하여 Linux 가상 머신에 액세스할 수 있습니다.You can easily create a Linux virtual machine on Azure and access it using Remote Desktop from Windows. Python이 기본적으로 설치되어 있으므로 VM에 Ubuntu를 사용하면 편리합니다. 그렇지 않은 경우 추가 Python 다운로드 위치는 원하는 Python 인터프리터 설치를 참조하세요.Ubuntu for the VM is convenient because Python is installed by default; otherwise, see the list on Install a Python interpreter of your choice for additional Python download locations.

Azure VM에 대한 방화벽 규칙을 만드는 방법에 대한 자세한 내용은 Azure Portal을 사용하여 Azure에서 VM으로 포트 열기를 참조하세요.For details on creating a firewall rule for an Azure VM, see Open ports to a VM in Azure using the Azure portal.

디버그할 스크립트 준비Prepare the script for debugging

  1. 원격 컴퓨터에서 다음 코드를 사용하여 guessing-game.py라는 Python 파일을 만듭니다.On the remote computer, create a Python file called guessing-game.py with the following code:

    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))
    
  2. pip3 install debugpy를 사용하여 사용자 환경에 debugpy 패키지를 설치합니다.Install the debugpy package into your environment using pip3 install debugpy.

    참고

    문제 해결에 필요한 경우를 대비하여 debugpy 버전을 기록해 두는 것이 좋습니다. debugpy 목록은 사용 가능한 버전도 보여줍니다.It's a good idea to record the version of debugpy that's installed in case you need it for troubleshooting; the debugpy listing also shows available versions.

  3. guessing-game.py에서 가능한 가장 빠른 지점에 다른 코드보다 먼저 해당 코드를 추가하여 원격 디버깅을 사용하도록 설정합니다.Enable remote debugging by adding the code below at the earliest possible point in guessing-game.py, before other code. (엄격한 요구 사항은 아니지만, listen 함수를 호출하기 전에 생성된 모든 백그라운드 스레드를 디버그할 수는 없습니다.)(Though not a strict requirement, it's impossible to debug any background threads spawned before the listen function is called.)

    import debugpy
    debugpy.listen(5678)
    
  4. 파일을 저장하고 python3 guessing-game.py를 실행합니다.Save the file and run python3 guessing-game.py. listen에 대한 호출이 백그라운드에서 실행되고, 달리 프로그램과 상호 작용하지 않으면 들어오는 연결을 기다립니다.The call to listen runs in the background and waits for incoming connections as you otherwise interact with the program. 원하는 경우 디버거가 연결될 때까지 listen 뒤에 wait_for_client 함수를 호출하여 프로그램을 차단할 수 있습니다.If desired, the wait_for_client function can be called after listen to block the program until the debugger attaches.

listenwait_for_client 외에도 debugpy는 디버거가 연결되어 있으면 중단점을 프로그래밍 방식으로 작동하는 breakpoint 도우미 함수를 제공합니다.In addition to listen and wait_for_client, debugpy also provides a helper function breakpoint, which serves as a programmatic breakpoint if the debugger is attached. 또한 디버거가 연결되어 있으면 True를 반환하는 is_client_connected 함수도 있지만, 다른 debugpy 함수를 호출하기 전에 이 결과를 확인할 필요가 없습니다.There is also an is_client_connected function that returns True if the debugger is attached (note that there is no need to check this result before calling any other debugpy functions).

Python 도구에서 원격으로 연결Attach remotely from Python Tools

이 단계에서는 간단한 중단점을 설정하여 원격 프로세스를 중지합니다.In these steps, we set a simple breakpoint to stop the remote process.

  1. 로컬 컴퓨터에 원격 파일의 복사본을 만들고 Visual Studio에서 엽니다.Create a copy of the remote file on the local computer and open it in Visual Studio. 파일의 위치는 중요하지 않지만, 이름은 원격 컴퓨터의 스크립트 이름과 일치해야 합니다.It doesn't matter where the file is located, but its name should match the name of the script on the remote computer.

  2. (선택 사항) 로컬 컴퓨터에서 debugpy에 IntelliSense를 사용하려면 Python 환경에 debugpy 패키지를 설치합니다.(Optional) To have IntelliSense for debugpy on your local computer, install the debugpy package into your Python environment.

  3. 디버그 > 프로세스에 연결을 선택합니다.Select Debug > Attach to Process.

  4. 나타나는 프로세스에 연결 대화 상자에서 연결 형식Python 원격(debugpy) 으로 설정합니다.In the Attach to Process dialog that appears, set Connection Type to Python remote (debugpy).

  5. 연결 대상 필드에 tcp://<ip_address>:5678을 입력합니다. 여기서 <ip_address>는 원격 컴퓨터의 IP 주소이고(명시적 주소 또는 myvm.cloudapp.net과 같은 이름일 수 있음), :5678은 원격 디버깅 포트 번호입니다.In the Connection Target field, enter tcp://<ip_address>:5678 where <ip_address> is that of the remote computer (which can be either an explicit address or a name like myvm.cloudapp.net), and :5678 is the remote debugging port number.

  6. Enter 키를 눌러 해당 컴퓨터에서 사용할 수 있는 debugpy 프로세스의 목록을 채웁니다.Press Enter to populate the list of available debugpy processes on that computer:

    연결 대상 입력 및 프로세스 나열

    이 목록을 채운 후 원격 컴퓨터에서 다른 프로그램을 시작하게 되는 경우 새로 고침 단추를 선택합니다.If you happen to start another program on the remote computer after populating this list, select the Refresh button.

  7. 디버그할 프로세스를 선택한 다음 연결을 선택하거나 프로세스를 두 번 클릭합니다.Select the process to debug and then Attach, or double-click the process.

  8. 그러면 스크립트가 원격 컴퓨터에서 계속 실행되는 동안 Visual Studio에서 디버깅 모드로 전환하여 모든 일반적인 디버깅 기능을 제공합니다.Visual Studio then switches into debugging mode while the script continues to run on the remote computer, providing all the usual debugging capabilities. 예를 들어 if guess < number: 줄에 중단점을 설정한 다음 원격 컴퓨터로 전환하고 다른 guess를 입력합니다.For example, set a breakpoint on the if guess < number: line, then switch over to the remote computer and enter another guess. 이렇게 하고 나면 로컬 컴퓨터의 Visual Studio가 해당 중단점에서 중지하고 로컬 변수 등을 보여 줍니다.After you do so, Visual Studio on your local computer stops at that breakpoint, shows local variables, and so on:

    Visual Studio에서 중단점이 적중될 때 디버깅 일시 중지

  9. 디버깅을 중지하면 Visual Studio는 원격 컴퓨터에서 계속 실행되는 프로그램에서 분리됩니다.When you stop debugging, Visual Studio detaches from the program, which continues to run on the remote computer. 또한 debugpy는 계속 디버거 연결을 수신 대기하므로 언제든지 프로세스에 다시 연결할 수 있습니다.debugpy also continues listening for attaching debuggers, so you can reattach to the process again at any time.

연결 문제 해결Connection troubleshooting

  1. 연결 형식Python 원격(debugpy) 을 선택했는지 확인합니다.Make sure that you've selected Python remote (debugpy) for the Connection Type

  2. 연결 대상의 비밀이 원격 코드의 비밀과 정확히 일치하는지 확인합니다.Check that the secret in the Connection Target exactly matches the secret in the remote code.

  3. 연결 대상의 IP 주소가 원격 컴퓨터의 IP 주소와 일치하는지 확인합니다.Check that the IP address in the Connection Target matches that of the remote computer.

  4. 원격 컴퓨터에서 원격 디버깅 포트를 열었는지와 연결 대상에 :5678과 같은 포트 접미사를 포함했는지 확인합니다.Check that you've opened the remote debugging port on the remote computer, and that you've included the port suffix in the connection target, such as :5678.

    • 다른 포트를 사용해야 하는 경우에는 debugpy.listen((host, port))와 같이 listen에 포트를 지정할 수 있습니다.If you need to use a different port, you can specify it in the listen, as in debugpy.listen((host, port)). 이 경우 방화벽에서 해당 특정 포트를 엽니다.In this case, open that specific port in the firewall.
  5. pip3 list로 반환된 원격 컴퓨터에 설치된 debugpy 버전이 Visual Studio에서 사용 중인 Python 도구 버전에서 사용되는 debugpy 버전과 일치하는지 아래 표에서 확인합니다.Check that the version of debugpy installed on the remote computer as returned by pip3 list matches that used by the version of the Python tools you're using in Visual Studio in the table below. 필요한 경우 원격 컴퓨터에서 debugpy를 업데이트합니다.If necessary, update debugpy on the remote computer.

    Visual Studio 버전Visual Studio version Python 도구/debugpy 버전Python tools/debugpy version
    2019 16.62019 16.6 1.0.0b51.0.0b5
    2019 16.52019 16.5 1.0.0b11.0.0b1

참고

Visual Studio 2019 버전 16.0~16.4는 debugpy가 아닌 ptvsd를 사용했습니다.Visual Studio 2019 version 16.0-16.4 utilized ptvsd, not debugpy. 이 연습에서 이러한 버전에 대한 프로세스는 유사하지만 함수 이름은 다릅니다.The process in this walkthrough for those versions is similar, but the function names are different. Visual Studio 2019 버전 16.5는 debugpy를 사용하지만 함수 이름은 ptvsd에서와 동일합니다.Visual Studio 2019 version 16.5 uses debugpy, but the function names were the same as those in ptvsd. listen 대신 enable_attach를 사용합니다.Instead of listen, you would use enable_attach. wait_for_client 대신 wait_for_attach를 사용합니다.Instead of wait_for_client, you would use wait_for_attach. breakpoint 대신 break_into_debugger를 사용합니다.Instead of breakpoint, you would use break_into_debugger.

레거시 디버깅에 ptvsd 3.x 사용Using ptvsd 3.x for legacy debugging

Visual Studio 2017 버전 15.8 이상에서는 ptvsd 버전 4.1 이상에 기반한 디버거를 사용합니다.Visual Studio 2017 versions 15.8 and later use a debugger based on ptvsd version 4.1+. Visual Studio 2019 버전 16.5 이상에서는 debugpy에 기반한 디버거를 사용합니다.Visual Studio 2019 versions 16.5 and later use a debugger based on debugpy. 이러한 버전의 디버거는 Python 2.7 및 Python 3.5 이상과 호환됩니다.These versions of the debugger are compatible with Python 2.7 and Python 3.5+. Python 2.6, 3.1~3.4 또는 IronPython을 사용하는 경우 Visual Studio에서는 디버거는 이 Python 환경을 지원하지 않습니다. 라는 오류를 표시합니다.If you're using Python 2.6, 3.1 to 3.4, or IronPython, Visual Studio shows the error, Debugger does not support this Python environment. 다음 정보는 ptvsd 3.x를 사용하는 원격 디버깅에만 적용됩니다.The following information applies only to remote debugging with ptvsd 3.x.

  1. ptvsd 3.x에서 enable_attach 함수를 사용하려면 실행 중인 스크립트에 대한 액세스를 제한하는 첫 번째 인수로 “secret”을 전달해야 했습니다.With ptvsd 3.x, the enable_attach function required that you pass a "secret" as the first argument that restricts access to the running script. 원격 디버거를 연결할 때 이 비밀을 입력합니다.You enter this secret when attaching the remote debugger. (권장되지는 않지만, enable_attach(secret=None)를 사용하여 모든 사용자의 연결을 허용할 수 있습니다.)Though not recommended, you can allow anyone to connect, use enable_attach(secret=None).

  2. 연결 대상 URL은 tcp://<secret>@<ip_address>:5678입니다. 여기서 <secret>은 Python 코드의 enable_attach에 전달된 문자열입니다.The connection target URL is tcp://<secret>@<ip_address>:5678 where <secret> is the string passed enable_attach in the Python code.

기본적으로 ptvsd 3.x 원격 디버그 서버에 대한 연결은 비밀로만 보호되고 모든 데이터는 일반 텍스트로 전달됩니다.By default, the connection to the ptvsd 3.x remote debug server is secured only by the secret and all data is passed in plain text. 보다 안전한 연결을 위해 ptvsd 3.x에서는 다음과 같이 설정하는 tcsp 프로토콜을 사용하여 SSL을 지원합니다.For a more secure connection, ptvsd 3.x supports SSL using the tcsp protocol, which you set up as follows:

  1. 원격 컴퓨터에서 다음과 같이 openssl을 사용하여 별도의 자체 서명된 인증서 및 키 파일을 생성합니다.On the remote computer, generate separate self-signed certificate and key files using openssl:

    openssl req -new -x509 -days 365 -nodes -out cert.cer -keyout cert.key
    

    openssl에서 메시지를 표시하면 일반 이름에 대해 호스트 이름 또는 IP 주소(어느 쪽이든 연결에 사용하는 항목)를 사용합니다.When prompted, use the hostname or IP address (whichever you use to connect) for the Common Name when prompted by openssl.

    (자세한 내용은 Python ssl 모듈 문서의 Self-signed certificates(자체 서명된 인증서)를 참조하세요.(See Self-signed certificates in the Python ssl module docs for additional details. 해당 문서의 명령은 결합된 단일 파일만 생성합니다.)Note that the command in those docs generates only a single combined file.)

  2. 코드에서 파일 이름을 값으로 사용하는 certfilekeyfile 인수를 포함하도록 enable_attach에 대한 호출을 수정합니다(이러한 인수는 표준 ssl.wrap_socket Python 함수에 대해 같은 의미를 지님).In the code, modify the call to enable_attach to include certfile and keyfile arguments using the filenames as the values (these arguments have the same meaning as for the standard ssl.wrap_socket Python function):

    ptvsd.enable_attach(secret='my_secret', certfile='cert.cer', keyfile='cert.key')
    

    로컬 컴퓨터의 코드 파일에서도 같은 변경을 수행할 수 있지만, 이 코드는 실제로 실행되지 않으므로 필요 없습니다.You can also make the same change in the code file on the local computer, but because this code isn't actually run, it isn't strictly necessary.

  3. 원격 컴퓨터에서 Python 프로그램을 다시 시작하여 디버깅을 준비합니다.Restart the Python program on the remote computer, making it ready for debugging.

  4. Visual Studio가 설치된 Windows 컴퓨터에서 신뢰할 수 있는 루트 CA에 인증서를 추가하여 채널을 보호합니다.Secure the channel by adding the certificate to Trusted Root CA on the Windows computer with Visual Studio:

    1. 로원격 컴퓨터의 인증서 파일을 로컬 컴퓨터에 복사합니다.Copy the certificate file from the remote computer to the local computer.
    2. 제어판을 열고 관리 도구 > 컴퓨터 인증서 관리로 이동합니다.Open Control Panel and navigate to Administrative Tools > Manage computer certificates.
    3. 나타나는 창의 왼쪽에서 신뢰할 수 있는 루트 인증 기관을 확장하고, 인증서를 마우스 오른쪽 단추로 클릭하고, 모든 작업 > 가져오기를 선택합니다.In the window that appears, expand Trusted Root Certification Authorities on the left side, right-click Certificates, and select All Tasks > Import.
    4. 원격 컴퓨터에서 복사한 .cer 파일로 이동하여 이 파일을 선택한 다음, 대화 상자를 클릭하여 가져오기를 완료합니다.Navigate to and select the .cer file copied from the remote computer, then click through the dialogs to complete the import.
  5. 앞에서 설명한 대로 Visual Studio에서 연결 프로세스를 반복하고 이제 연결 대상(또는 한정자)에 대한 프로토콜로 tcps://를 사용합니다.Repeat the attach process in Visual Studio as described earlier, now using tcps:// as the protocol for the Connection Target (or Qualifier).

    SSL로 원격 디버깅 전송 선택

  6. SSL을 통해 연결하면 Visual Studio에서 잠재적인 인증서 문제에 대한 메시지를 표시합니다.Visual Studio prompts you about potential certificate issues when connecting over SSL. 경고를 무시하고 계속할 수 있지만, 채널이 여전히 도청으로부터 암호화되더라도 메시지 가로채기(man-in-the-middle) 공격에 개방될 수 있습니다.You may ignore the warnings and proceed, but although the channel is still encrypted against eavesdropping it can be open to man-in-the-middle attacks.

    1. 아래의 원격 인증서를 신뢰할 수 없습니다. 경고가 표시되는 경우 신뢰할 수 있는 루트 CA에 인증서를 제대로 추가하지 않았음을 의미합니다.If you see the remote certificate is not trusted warning below, it means you did not properly add the certificate to the Trusted Root CA. 해당 단계를 확인하고 다시 시도합니다.Check those steps and try again.

      SSL 인증서를 신뢰할 수 있습니다. 경고

    2. 아래의 원격 인증서 이름이 호스트 이름과 일치하지 않습니다. 경고가 표시되는 경우 인증서를 만들 때 일반 이름으로 올바른 호스트 이름 또는 IP 주소를 사용하지 않았음을 의미합니다.If you see the remote certificate name does not match hostname warning below, it means you did not use the proper hostname or IP address as the Common Name when creating the certificate.

      SSL 인증서 호스트 이름 경고