Symbols for mixed-mode Python/C++ debugging - Visual Studio (Windows) (original) (raw)

This article provides steps to download and integrate debugging symbols for Python interpreters in Visual Studio.

To provide a full debugging experience, the mixed-mode Python debugger in Visual Studio needs debug symbols for the Python interpreter to parse numerous internal data structures. The debugging symbols are defined in program database (.pdb) files. For example, the python27.dll library requires the python27.pdb symbol file, the python36.dll library uses the symbol file python36.pdb, and so on. Each version of the interpreter also supplies symbol files for various modules.

• In Visual Studio 2017 and later, the Python 3 and Anaconda 3 interpreters automatically install their respective symbols and Visual Studio finds the symbols automatically.
• In Visual Studio 2015 and earlier, or for other interpreters, you need to download symbols separately and then point Visual Studio to the files.

When Visual Studio detects missing required symbols, a dialog prompts you to take action. You typically see the dialog when you start a mixed-mode debugging session. The dialog includes the Open symbol settings dialog link, which opens the Tools > Options dialog to the Debugging > Symbols tab, along with a link to this documentation article.

Prerequisites

• Visual Studio installed with support for Python workloads. For more information, see Install Python support in Visual Studio.

Check your interpreter version

Symbols differ between minor builds of Python and between 32-bit and 64-bit builds. It's important to confirm your version and build of Python to ensure you have the correct symbols for your interpreter.

To check which Python interpreter is in use:

1. In Solution Explorer, expand the Python Environments node under your project.
2. Locate the name of the current environment (shown in bold).
3. Right-click the environment name and select Open Command Prompt Here.
   A command prompt window opens to the install location of the current environment.
4. Start python by entering the following command:

python.exe  

The execution process displays your installed Python version and indicates whether it's 32-bit or 64-bit:

Download symbols

The following steps describe how to download the required symbols for a Python interpreter.

• For Python 3.5 and later, acquire the debug symbols through the Python installer.
  1. Select Custom installation, then select Next.
  2. On the Advanced Options page, select the boxes for Download debugging symbols and Download debug binaries:
     
     The symbol files (.pdb) are located in the root installation folder. Symbol files for individual modules are also placed in the DLLs folder.
     Visual Studio finds these symbols automatically. No further steps are needed.
• For Python 3.4.x and earlier, symbols are available as downloadable .zip files from the official distributions or from Enthought Canopy.
  1. Download your required symbol file.
     Important
     Be sure to select the symbol file that corresponds to your installed Python version and build (32-bit or 64-bit).
  2. Extract the symbol files to a local folder within the Python folder, such as Symbols.
  3. After you extract the files, the next step is to Point Visual Studio to the symbols.
• For other third-party Python distributions such as ActiveState Python, contact the authors of that distribution and request them to provide you with symbols.
  WinPython incorporates the standard Python interpreter without changes. You can use symbols from the official WinPython distribution for the corresponding version number.

Point Visual Studio to the symbols

If you downloaded symbols separately, follow these steps to make Visual Studio aware of the symbols.

Note

If you installed symbols by using the Python 3.5 or later installer, Visual Studio finds the symbols automatically. You don't need to complete the steps in this section.

1. Select Tools > Options, and open the Debugging > Symbols tab.
2. Select Add (plus symbol) on the toolbar.
3. Enter the folder path where you extracted the downloaded symbols. This location is where the python.pdb file is located, such as c:\python34\Symbols, as shown in the following image.
   
4. Select OK.

During a debugging session, Visual Studio might also prompt you for the location of a source file for the Python interpreter. If you downloaded source files, such as from python.org/downloads/, you can point Visual Studio to the downloaded files.

Symbol caching options

The Tools > Options, Debugging > Symbols dialog also contains options to configure symbol caching. Visual Studio uses the symbol caching features to create a local cache of symbols obtained from an online source.

These features aren't needed with the Python interpreter symbols because symbols are already present locally. For more information, see Specify symbols and source files in the Visual Studio debugger.

Access downloads for official distributions

The following table lists download information for official Python version releases.

Use Enthought Canopy symbols

Enthought Canopy provides debugging symbols for its binaries starting from version 1.2. These symbols are automatically installed alongside with the distribution.

• To use the symbols, manually add the folder that contains the symbols to the symbol path, as described in Point Visual Studio to the symbols.
  For a typical per-user installation of Canopy, the symbols are located in the following folders:
  • 64-bit version: %UserProfile%\AppData\Local\Enthought\Canopy\User\Scripts
  • 32-bit version: %UserProfile%\AppData\Local\Enthought\Canopy32\User\Scripts

Enthought Canopy 1.1 and earlier and Enthought Python Distribution (EPD), don't provide interpreter symbols. These releases aren't compatible with mixed-mode debugging.

Related content

• Specify symbols and source files in the Visual Studio debugger
• Debug Python and C++ together (mixed-mode debugging)