Develop with Q# Jupyter Notebooks

Install the QDK for developing Q# operations on Q# Jupyter Notebooks.

Jupyter Notebooks allow in-place code execution alongside instructions, notes, and other content. This environment is ideal for writing Q# code with embedded explanations or quantum computing interactive tutorials. Here's what you need to do to start creating your own Q# notebooks.


  • In Q# Jupyter Notebooks, you can only run Q# code, and the operations cannot be called from external host programs (e.g. Python or C# files). This environment is not appropriate if your goal is to combine an external classical host program with the quantum program.

Install the IQ# Jupyter kernel

IQ# (pronounced i-q-sharp) is an extension primarily used by Jupyter and Python to the .NET Core SDK that provides the core functionality for compiling and simulating Q# operations.

  1. Install Miniconda or Anaconda. Note: 64-bit installation required.

  2. Open an Anaconda Prompt.

    • Or, if you prefer to use PowerShell or pwsh: open a shell, run conda init powershell, then close and re-open the shell.
  3. Create and activate a new conda environment named qsharp-env with the required packages (including Jupyter Notebook and IQ#) by running the following commands:

    conda create -n qsharp-env -c quantum-engineering qsharp notebook
    conda activate qsharp-env
  4. Run python -c "import qsharp" from the same terminal to verify your installation and populate your local package cache with all required QDK components.

That's it! You now have the IQ# kernel for Jupyter, which provides the core functionality for compiling and executing Q# operations from Q# Jupyter Notebooks.

Create your first Q# notebook

Now you are ready to verify your Q# Jupyter Notebook installation by writing and executing a simple Q# operation.

  1. From the environment you created during installation (i.e., either the conda environment you created, or the Python environment where you installed Jupyter), run the following command to start the Jupyter Notebook server:

    jupyter notebook
    • If the Jupyter Notebook doesn't open automatically in your browser, copy and paste the URL provided by the command line into your browser.
  2. Choose "New" → "Q#" to create a Jupyter Notebook with a Q# kernel, and add the following code to the first notebook cell:

    operation SampleQuantumRandomNumberGenerator() : Result {
        using (q = Qubit())  { // Allocate a qubit.
            H(q);             // Put the qubit to superposition. It now has a 50% chance of being 0 or 1.
            let r = M(q);     // Measure the qubit value.
            return r;
  3. Run this cell of the notebook:

    Jupyter Notebook cell with Q# code

    You should see SampleQuantumRandomNumberGenerator in the output of the cell. When running in Jupyter Notebook, the Q# code is compiled, and the cell outputs the name of any operations that it finds.

  4. In a new cell, execute the operation you just created (in a simulator) by using the %simulate command:

    Jupyter Notebook cell with %simulate magic

    You should see the result of the operation you invoked. In this case, because your operation generates a random result, you will see either Zero or One printed on the screen. If you execute the cell repeatedly, you should see each result approximately half the time.

Next steps

Now that you have installed the QDK for Q# Jupyter Notebooks, you can write and run your first quantum program by writing Q# code directly within the Jupyter Notebook environment.

For more examples of what you can do with Q# Jupyter Notebooks, please take a look at:

  • Intro to Q# and Jupyter Notebook. There you will find a Q# Jupyter Notebook that provides more details on how to use Q# in the Jupyter environment.
  • Quantum Katas, an open-source collection of self-paced tutorials and sets of programming exercises in the form of Q# Jupyter Notebooks. The Quantum Katas tutorial notebooks are a good starting point. The Quantum Katas are aimed at teaching you elements of quantum computing and Q# programming at the same time. They're an excellent example of what kind of content you can create with Q# Jupyter Notebooks.