Get started with a Jupyter notebook and Q# in Azure Quantum


Once you have created an Azure Quantum workspace, there are many ways to start running your code in Azure Quantum. A Jupyter notebook is a document that contains both rich text and code and can run in your browser, and can run Q# and Python code in Azure Quantum. Notebooks can be created directly in the Azure Quantum portal, and offer features such as preloaded connection information and standard Q# libraries.

You will learn more about Jupyter notebooks in Azure Quantum workspace in future lessons.

To get started, copy the sample notebook from the notebook gallery.

  1. Select your Azure Quantum workspace in the Azure portal.
  2. Select Notebooks.
  3. Select Sample gallery.
  4. Locate the Hello, world: Q# notebook tile, select either the IonQ or Quantinuum provider (the sample code is identical) and select Copy to my notebooks..
  5. The sample notebook can be found under My notebooks and you can now run the notebook.

Load a sample Jupyter notebook

The notebook first imports the required packages for the sample, then connects to the Azure Quantum service, and then runs a Q# program.

To run the sample notebook, follow these steps for your selected provider.

  1. In My notebooks, select the hello-world-qsharp-ionq notebook.
  2. To run the full program from top to bottom, select Run all.
  3. To walk through the example and run each cell individually from top to bottom, select the cell you want to run and select the run icon.

Run a Jupyter notebook.

Stepping through the program on IonQ

The hello world program runs a simple quantum random number generator and displays a histogram of the results.

Some things to note:

  • The kernel: In the upper right of the notebook, you can see that the notebook is running the Python 3 (ipykernel) kernel, which is the default Python shell for Juptyer Notebooks. When you create a notebook in Azure Quantum, you can select either the Python 3 (ipykernel) or the Azure Quantum Q# kernel. Both kernels are fully compatible with Q# code.
  • 1st cell: Preloads your subscription information to connect to the Azure Quantum service.
  • 2nd cell: Retrieves the available targets (quantum computers and simulators) in your workspace.
  • 3rd and 4th cells: The Q# code that defines the program. Note the %%qsharp magic command which allows you to enter Q# code directly into the notebook when using the Python 3 (ipykernel).
  • 5th cell: Sets the target and submits the job.
  • 6th and 7th cells: Plots and displays the result. The results should be roughly split between 0 and 1.


If you have any questions regarding the workspace creation process or run into any issue at any point using Azure Quantum, bookmark Azure Quantum office hours and join our open office hours every Thursday 8∶30 AM Pacific Standard Time zone (PST).