Build and Debug Instructions for PTVS

Cloning

First, you will require a local copy of our Git repository. It can be cloned from https://github.com/Microsoft/PTVS.git. (If you're behind a corporate firewall you may need to enter your proxy settings.)

Branch Selection:

• For Dev17 (Visual Studio 2022): Check out the release/dev17 branch
• For Dev18 (Visual Studio 2026): Check out the main branch

If you intend to contribute back to PTVS, you should Create a Fork and use the source URL provided there. Pull requests associated with an issue or feature request are the preferred way for making contributions.

Prerequisites

For Dev17 (Visual Studio 2022)

1. Install Visual Studio 2022 Preview Community edition or higher
   • Install the following workloads:
     • .NET desktop development
     • Desktop development with C++
     • Visual Studio extension development
     • ASP.NET and web development
       • Only if you intend to build Django
     • DO NOT install the Python workload into the Visual Studio version you are going to be building PTVS with.
       • You CAN install the Python workload into other Visual Studio versions.
   • Install the following individual components (see https://aka.ms/Ofhn4c for more info):
     • MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (Latest)
     • C++ ATL for latest v143 build tools with Spectre Mitigations (x86 & x64)
     • C++ MFC for latest v143 build tools with Spectre Mitigations (x86 & x64)

For Dev18 (Visual Studio 2026)

1. Install Visual Studio Dev18 Preview Community edition or higher
   • Install the following workloads:
     • .NET desktop development
     • Desktop development with C++
     • Visual Studio extension development
     • ASP.NET and web development
       • Only if you intend to build Django
     • DO NOT install the Python workload into the Visual Studio version you are going to be building PTVS with.
       • You CAN install the Python workload into other Visual Studio versions.
   • Install the following individual components:
     • MSVC v145 build tools
     • C++ ATL for latest v145 build tools with Spectre Mitigations (x86 & x64)
     • C++ MFC for latest v145 build tools with Spectre Mitigations (x86 & x64)

Common Prerequisites (Both Dev17 and Dev18)

1. Open a Visual Studio command prompt as Administrator, change to the root of where you cloned the PTVS repo, and run .\Python\Prerequisites\deploy_test_targets.cmd

2. Right-click on <repopath>\Python\Prerequisites\EnableSkipVerification.reg (or …X86.reg on 32-bit OS) and click on merge

   • This disables strong name verification for the built binaries.
   • If you've already run \\vspreinstall\preinstall\preinstall.cmd, you can skip the registry script
   • If you get exception on missing target, either you forgot to run deploy_test_targets.cmd or VS install dir in the deploy_test_targets.cmd is incorrect. Fix the location and try again.

3. Install nodejs/npm from https://nodejs.org/en/download/

4. MICROSOFT EMPLOYEES ONLY - Install the azure artifacts credential provider.

   • To do this, open a new powershell prompt and run the following: iex "& { $(irm https://aka.ms/install-artifacts-credprovider.ps1) } -AddNetfx"
   • If this doesn't work, you can download the ps1 file and run it manually. See https://github.com/microsoft/artifacts-credprovider for more info.

5. MICROSOFT EMPLOYEES ONLY - Install the vsts-npm-auth package through npm. This will allow the script to download pylance from the azure artifacts feed as part of the next step. You will need to run the second command as an administrator, and it needs to be run from the root of the cloned repository. You may need to temporarily change the execution policy for Powershell as described in the next step:

   • npm install -g vsts-npm-auth
   • vsts-npm-auth -config .npmrc -force

6. Restore npm and nuget packages by running powershell .\Build\PreBuild.ps1

   • If you get an error about not being allowed to run scripts, you may need to change the execution policy on your machine. From a PowerShell run as administrator, you can use Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine to allow local script execution. Once done you should probably go back to prior restrictions (typically done with Set-ExecutionPolicy -ExecutionPolicy AllSigned -Scope LocalMachine).
   • If you get 401 unauthorized errors...
     • If you ARE a Microsoft Employee, you need to authenticate. To do this, run .\Build\PreBuild.ps1 -interactive. After you login, a personal access token will be created for you. You won't need to do this again until the token expires. You will get an e-mail about the token, and you can browse to it and extend the expiration date by quite a while.
     • If you are NOT a Microsoft Employee, this should never happen to you. If it does, please create an issue in the PTVS repo and our team will get it fixed.

7. BUILD WITH MSBUILD BEFORE BUILDING THROUGH VISUAL STUDIO (SEE BELOW)

Building with MSBuild

Building from the command line does NOT install PTVS into the VS Experimental hive (by default), nor create an installer, nor affect your main VS installation.

(The Exp hive is an isolated VS environment which allows you to install things without affecting your main VS install. It exists so you can work in parallel with your main install and you can blow it away if you break something.)

• Note, you need to run the build and deploy from the command line step at least once for deployment to work in the IDE.

1. To build from the command line, run the following in your VS developer shell from your repo root folder:

   msbuild Python\dirs.proj
   

2. To build AND deploy to the Experimental hive, run the following based on your target version:

   For Dev17 (Visual Studio 2022):

   msbuild Python\dirs.proj /p:VSTarget=17.0 /p:DeployExtension=true /p:RegisterOutputPackage=true
   

   For Dev18 (Visual Studio 2026):

   msbuild Python\dirs.proj /p:VSTarget=18.0 /p:DeployExtension=true /p:RegisterOutputPackage=true
   

   • If you get errors when deploying the Python - C++ project debugging support extension to the Exp hive, it's probably due to path length issues. Follow the steps at https://www.tenforums.com/tutorials/51704-enable-disable-win32-long-paths-windows-10-a.html#option1 to enable long paths and try again.

3. To launch the VS Experimental hive, open the Visual Studio Command Prompt and run the following:

   devenv /rootSuffix Exp
   

Building and debugging with Visual Studio

PTVS is packaged into several VSIX packages that get installed into the Visual Studio Experimental (Exp) Hive when you build.

1. Open ./Python/PythonTools.sln in Visual Studio and select Product\Core as the Startup Project.
2. Push F5 to build and run
   • This will launch the Exp instance of VS through the debugger, with all the Python extensions installed.
     • This is indicated by Exp in the upper right corner of the VS window.
   • If an error appears rather than a new instance of VS, ensure the Project|Debug settings are correctly starting your devenv.exe with arguments /rootSuffix Exp (and optionally /log).
   • Sometimes the updated vsix packages don't get installed to the Exp hive. A rebuild will usually fix this.
3. To debug, set breakpoints in the non-Exp instance of Visual Studio, and perform actions in the Exp instance.

Optional Projects

Core projects are always required to be built, and you will receive build errors if you unload one by mistake. They are grouped under the CoreProduct solution folder. The PythonTools.sln solution file includes a solution platform called "Minimal" that may be selected within Visual Studio to only build these projects. This will give the fastest possible build times, while only providing core functionality.

Projects under the "Product" solution folder are optional and may be unloaded to reduce build time. Once they are built, you should Clean the solution before unloading them. Note that some of the tests require these projects.

Projects under the "Tests" solution folder are also optional, but as we expect tests to be added or fixed for contributions you will likely need to run some of them. We do not require 100% test pass rate to accept a pull request, as there are a number of tests that rely on precise system configuration or are known to be unreliable.

Clearing the Exp hive

Sometimes the Exp hive can get corrupted, which leads to all sorts of problems. The safest way to clear it is to just delete it, since a new one will be created the next time you build and run.

1. Browse to %localappdata%\Microsoft\VisualStudio
   • For example, C:\Users\<yourUserName>\AppData\Local\Microsoft\VisualStudio
2. Look for folders starting with your Visual Studio major version and ending in Exp
   • For Dev17: 17.0_xxxxxxxxExp
   • For Dev18: 18.0_xxxxxxxxExp
3. Delete all of the folders that match what you found from the previous step

Running Automated Tests

PTVS contains a large number of automated tests, including a mix of UI-based tests (which will start another VS, take control of your mouse, etc.) and non-UI tests. Some of the UI-based tests may fail intermittently or interfere with each other, while some tests may make incorrect assumptions about your system configuration (such as the availability of certain versions of Python). It is best to select the tests you need from the Test Explorer window and supervise them as they run.