Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
The Microsoft Quantum Development Kit (QDK) uses the standard functionality of Visual Studio Code (VS Code), along with language-specific features when you work with .qs or .qasm files. This reference guide describes the principal QDK commands that you can access in the VS Code Command Palette, along with other features and links to additional content. For general VS Code guidance, see the VS Code documentation.
Most commands from the QDK extension are accessible from the View > Command Palette menu. Open the Command Palette and enter QDK: to view a filtered list of commands while in a .qs, .qasm, or .qsc file.
Tip
You can create custom keyboard shortcuts for VS Code commands using Keyboard Shortcuts, or Ctrl + K + S. For more information, see Key Bindings for VS Code.
Commands
Many of the QDK commands are related to writing and running Q# and OpenQASM programs, and are only available when a .qs, .qasm, or .qsc file is active. Other commands are generally available.
General commands
| Command | Action | Notes | Alternate user action |
|---|---|---|---|
| QDK: Create Q# project | Creates a Q# project in the active folder, including a qsharp.json manifest file and a src subfolder with a default main.qs file. |
For more information about Q# projects, see Working with Q# projects. | In File Explorer, right-click the target folder and select Create Q# project. |
| QDK: Create a Microsoft Quantum notebook | Opens a sample Jupyter Notebook that runs a Q# + Python program and submits a job to Azure Quantum. | For more information about the QDK in Jupyter Notebook, see Submit jobs to Azure Quantum with the QDK Python package. | N/A |
| QDK: Connect to an Azure Quantum workspace | Connect to an Azure Quantum workspace using your Azure account or a connection string. Once you're authenticated, select the Microsoft Quantum panel icon (bottom left). | For more information about Azure Quantum connections, see Connect to your Azure Quantum workspace. | Hover over Quantum workspaces and select the ＋ icon. |
| QDK: Open QDK playground | Opens an online folder of Q# and OpenQASM sample programs in File Explorer. You can edit and run the programs in the local quantum simulator, and also set breakpoints and step through the code with the built-in debugger. | For more information, see the README file in the sample folder. | N/A |
| QDK: Refresh Azure Quantum workspaces | Syncs the latest changes from your connected quantum workspaces. | If there's a connection issue, an alert icon appears next to the workspace name. | Hover over Quantum Workspaces and select the refresh icon. |
| QDK: Create a Microsoft Quantum Python virtual environment | Creates a folder and installs a Python virtual environment with the selected packages. | Available in desktop VS Code, but not VS Code for the Web. | N/A |
| QDK: Bloch sphere | Opens the Bloch sphere visualizer. | For more information, see How to use the Bloch sphere visualizer in the QDK. | N/A |
| QDK: Show Changelog | Opens a changelog in a new tab that shows the QDK updates for the current and all previous release versions. | The changelog is also available on the open-source QDK GitHub repository. | N/A |
| Explorer: Focus on Quantum Workspaces View | Opens File Explorer and focuses on your connected quantum workspaces, if configured. If no workspaces are configured, you're prompted to add an existing workspace. | For more information about Azure Quantum connections, see Connect to your Azure Quantum workspace. | N/A |
Commands available based on the active file type
| Command | Program file types | Action | Notes | Alternate user action |
|---|---|---|---|---|
| QDK: Show circuit | .qs, .qasm |
Displays a circuit diagram for the program before it runs. | For more information, see Visualize quantum circuit diagrams. | Select the code lens option Circuit from the menu next to the entry point operation or above each user-defined operation in the program. |
| QDK: Run file and show histogram | .qs, .qasm |
Runs the current program and displays a histogram of the results in a new pane. | To access the sort and filter options, select the filter icon in the histogram pane. | Select the code lens option Histogram from the menu next to the entry point operation. |
| QDK: Get QIR for current QDK program | .qs, .qasm |
Opens the QIR source for the current Q# or OpenQASM code in a new edit window. Your program must use the Base, Adaptive RI, or Adaptive RIF target profile to export QIR source. | For more information about QIR, see Quantum intermediate representation and the QDK developer blog. | N/A |
| QDK: Calculate Resource Estimates | .qs, .qasm |
Invokes the built-in version of the resource estimator. | For more information, see Introduction to the Microsoft Quantum resource estimator. | N/A |
| QDK: Help | .qs |
Opens a brief overview of the QDK extension in VS Code. | N/A | N/A |
| QDK: Run file and show circuit diagram | .qs, .qasm |
Runs the current program and displays a circuit of the program with outputs. | For more information, see Visualize quantum circuit diagrams. | N/A |
| QDK: Show API documentation | .qs |
Opens the API documentation in a new pane. To search this pane, press Ctrl + F. | For more information, see the Q# API reference. | N/A |
| Debug: Start Debugging | .qs, .qasm, .qsc |
Opens the current program in the debugger. | For more information, see Debugging and testing your quantum code. | Press F5, select the code lens option Debug next to the entry point operation, or select the Run icon in the upper-right corner and then select Start Debugging. |
| QDK: Run program | .qs, .qasm, .qsc |
Runs the current program in the default quantum simulator. | For more information, see Get started with Q# programs. | Press Ctrl + F5, select the code lens option Run next to the entry point operation, or select the Run icon in the upper-right corner and then select Run. |
Panel views
Q# and OpenQASM programs use the following views in the VS Code panel:
| View | Action |
|---|---|
| Debug console | Displays run output or debug output |
| Problems | Displays pre-compile error checks |
Edit Q# and OpenQASM code
Most of the common code editing features in VS Code are also available when you work with Q# and OpenQASM programs:
- Precompile error checking
- Go-to definition
- References
- Function signatures
- Parameter information
- Completion suggestions, including context-aware, namespace member, and type member completions.
- Linting - In Q# files, you configure linting per-project in the manifest file. For more information, see Working with Q# projects.
For more information, see IntelliSense in the VS Code documentation.
Common tasks
The following tables list commands for common tasks when you work with the QDK extension.
Work with Q# files and projects
| Task | Action | Notes |
|---|---|---|
| Create a new Q# file | Select File > New file > Text file. Save the file with a .qs extension. |
If you set Files: Default Language = qsharp, a new file automatically defaults to Q# formatting. |
| Create a Q# project | From an open folder in File Explorer, select QDK: Create Q# project from the Command Palette, or right-click the folder in File Explorer and select Create Q# project. | For more information about Q# projects, see Working with Q# projects. |
| Create a sample file | In a blank .qs or .qasm file, enter samples, and then choose a sample program from the list of options. |
You can also select QDK: Open QDK playground in the Command Palette to open an online folder of Q# and OpenQASM sample programs in File Explorer. |
Connect to Azure Quantum
| Task | Action | Notes | Alternate user action |
|---|---|---|---|
| Connect to an Azure Quantum workspace | Select the Microsoft Quantum panel icon (bottom left). From Quantum Workspaces select Add an existing workspace. Follow the prompts to select a subscription and workspace. | You can connect to multiple workspaces. Select ＋ next to Quantum Workspaces to connect another workspace. Workspace connections persist between your VS Code sessions. | From the Command Palette, select QDK: Connect to an Azure Quantum workspace. |
| Connect programmatically with a Python program | Right-click an existing workspace connection and select Copy Python code to connect to workspace. Paste the resulting code into your Python program. | For more information, see Submit jobs to Azure Quantum with the QDK Python package. | N/A |
Run programs
| Task | Action | Notes | Alternate user action |
|---|---|---|---|
| Run a Q# or OpenQASM program on the local quantum simulator | In a .qs or .qasm file, select the Run icon in the upper-right, and select Run. |
For more information on the quantum simulator, see the Sparse quantum simulator. | Press Ctrl + F5, or choose either QDK: Run file and show histogram or QDK: Run file and show circuit diagram in the Command Palette, or choose the Run code lens option above the entry point operation. |
| Debug a program | In a Q# or OpenQASM program, select the Run icon in the upper right, and then choose Start Debugging. | For more information about the Q# debugger in VS Code, see Debugging and testing your quantum code. | Press F5, or choose the code Debug code lens from the menu above the entry point operation. |
| View providers and targets in your workspaces | Select the Microsoft Quantum panel icon (bottom left). From Quantum Workspaces, expand the workspace, and then expand Providers to see the available providers in the workspace. Expand an individual provider to view the available targets. | Hover over a target name to view its Status and Queue time before you submit a job. | N/A |
| Submit a job to Azure Quantum | In a Q# or OpenQASM program, choose a workspace, provider, and target. To submit the current program, select the arrow next to the target. | For more information, see Submit jobs to Azure Quantum with the QDK extension for VS Code. | N/A |
| View job results | Expand the workspace and then expand Jobs. To open the job output from Azure Storage, select the cloud icon next to the job name. | Jobs are listed from newest to oldest. | N/A |