Develop with Q# and Python

Learn how to install the Quantum Development Kit (QDK) to develop Python host programs that call Q# operations.

Install the qsharp Python package

The qsharp Python package, which includes the IQ# kernel, contains the necessary functionality for compiling and simulating Q# operations from a regular Python program.

  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 initialization 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.

    Important

    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 both the qsharp Python package and the IQ# kernel for Jupyter, allowing you to compile and run Q# operations from Python and Q# Jupyter Notebooks.

Choose your IDE

While you can use Q# with Python in any IDE, we highly recommend using Visual Studio Code (VS Code) for your Q# + Python applications. With the QDK extension for VS Code you gain access to richer functionality such as warnings, syntax highlighting, project templates, and more.

If you would like to use VS Code:

VS Code also offers its own terminal from which you can run code. If you are using conda, make sure you follow the procedure detailed in the installation section to initialize conda for the shell used by VS Code. On Windows, VS Code will use PowerShell unless configured differently. Doing so will allow you to run Q# with Python programs directly from VS Code's integrated terminal, however you can use any terminal of your choice with access to Python. Remember to activate your Q# environment there before running any programs, using conda activate qsharp-env.

If you would like to use a different editor, the instructions so far have you all set.

Write your first Q# program

Now you are ready to verify your qsharp Python package installation by writing a simple Q# program and running it on a quantum simulator.

  1. Create a minimal Q# operation by creating a file called Operation.qs and adding the following code to it:

    namespace Qrng {
        open Microsoft.Quantum.Intrinsic;
    
        operation SampleQuantumRandomNumberGenerator() : Result {
            use 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.
            Reset(q);
            return r;
        }
    }
    
  2. In the same folder as Operation.qs, create the following Python program called host.py. This program imports the Q# operation SampleQuantumRandomNumberGenerator() defined in step 1 and runs it on the default simulator with a .simulate() call:

    import qsharp
    from Qrng import SampleQuantumRandomNumberGenerator
    
    print(SampleQuantumRandomNumberGenerator.simulate())
    
  3. From a terminal with access to your Python/Q# environment created during installation, navigate to your project folder and run the Python host program:

    python host.py
    
  4. You should see the result of the operation you invoked. In this case, because your operation generates a random result, you will see either 0 or 1 printed on the screen. If you run the program repeatedly, you should see each result approximately half the time.

Note

The Python code is just a normal Python program. You can use any Python environment, including Python-based Jupyter Notebooks, to write the Python program and call Q# operations. The Python program can import Q# operations from any .qs files located in the same folder as the Python code itself.

Next steps

Now that you have tested the Quantum Development Kit in your preferred environment, you can follow this tutorial to write and run your first quantum program.

For more information on how to run Q# programs with Python, see the following articles: