Develop with Q# Jupyter Notebooks

This article shows you how to install the Quantum Developer Kit (QDK) for developing Q# operations on Q# Jupyter Notebooks. Then, learn how to start developing your own Q# notebooks.

Jupyter Notebooks allow running code in-place alongside instructions, notes, and other content. This environment is ideal for writing Q# code with embedded explanations or quantum computing interactive tutorials.

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. Consult their installation guide if you are unsure about any steps. Note: 64-bit installation required.

  2. Initialize conda for your preferred shell with the conda init command. The steps below are tailored to your operating system:

    (Windows) Open an Anaconda Prompt by searching for it in the start menu. Then run the initialization command for your shell, e.g. conda init powershell cmd.exe will set up both the Windows PowerShell and Command Prompt for you. You can then close this prompt.


    To work with PowerShell, conda will configure a startup script to run whenever you launch a PowerShell instance. By default, the script's execution will be blocked on Windows, and requires modifying the PowerShell execution policy with the following command (executed from within PowerShell):

    Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

    (Linux) If haven't done so during installation, you can still initialize conda now. Open a terminal and navigate to the bin directory inside your selected install location (e.g. /home/ubuntu/miniconda3/bin). Then run the appropriate command for your shell, e.g. ./conda init bash. Close your terminal for the changes to take effect.

  3. From a new terminal, 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. Finally, run python -c "import qsharp" 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, allowing you to compile and run 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 running a simple Q# operation.

  1. From the environment you created during installation (that is, 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 {
        use q = Qubit(); // Allocate a qubit in the |0⟩ state.
        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;


Callables from Microsoft.Quantum.Intrinsic and Microsoft.Quantum.Canon (for example, the H operation belongs to Microsoft.Quantum.Intrinsic namespace) are automatically available to operations defined within cells in Q# Jupyter Notebooks. You don't need to open those namespaces in your Q# program. However, this is not true for code brought in from external Q# source files (a process shown at Intro to Q# and Jupyter Notebooks).

  1. Run this cell of the notebook. 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.

  2. In a new cell, run the operation you just created in a simulator by using the %simulate magic 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 run the cell repeatedly, you should see each result approximately half the time.


In a Jupyter Notebook, Q# code is automatically wrapped in a namespace for you. Since Q# does not feature nested namespaces, you should make sure not to declare any additional namespaces inside of code cells.

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.