Set up a Q# and Python environment

Learn how to configure a Python development environment 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.

Install using conda (recommended)

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, for example, 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 (for example, /home/ubuntu/miniconda3/bin). Then run the appropriate command for your shell, for example,./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 microsoft 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.

Install using .NET CLI and pip (advanced)

1. Prerequisites:

   • Python 3.6 or later
   • The PIP Python package manager
   • .NET SDK 6.0

2. Install the qsharp package, a Python package that enables interop between Q# and Python.

   pip install qsharp
   

3. Install IQ#, a kernel used by Jupyter and Python that provides the core functionality for compiling and running Q# operations.

   dotnet tool install -g Microsoft.Quantum.IQSharp
   dotnet iqsharp install
   

   Note

   If you encounter a permission error in Linux, install the IQ# kernel in user mode instead with dotnet iqsharp install --user.

   Note

   If you encounter an error and you just installed .NET, you won't be able to run the dotnet iqsharp install command immediately. Instead, under Windows, open a new terminal window and try again. Under Linux, log out of your session and log back in to try again. If this still doesn't work, try locating the installed dotnet-iqsharp tool (on Windows, dotnet-iqsharp.exe) and running:

   /path/to/dotnet-iqsharp install --user --path-to-tool="/path/to/dotnet-iqsharp"
   

   where /path/to/dotnet-iqsharp should be replaced by the absolute path to the dotnet-iqsharp tool in your file system. Typically this will be under .dotnet/tools in your user profile folder.

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.

Next steps

Now that you have set up your Python environment, you can write and run quantum programs against local quantum simulators or remote quantum hardware.