Run Your First Quantum Program on Azure Quantum

This guide walks you through creating and running your first quantum program on Microsoft Azure Quantum. You’ll write a simple quantum circuit using Q#, submit it to a quantum simulator (and optionally a real quantum computer), and see the results. By the end, you’ll have a working setup and understand the basic workflow.

What You’ll Need

An Azure account (free tier is fine for this). If you don’t have one, sign up at azure.microsoft.com/free.
An Azure Quantum workspace (we’ll create it in the steps).
Either VS Code with the Azure Quantum Development Kit extension, or you can use the Azure Quantum portal (no local install needed). We’ll cover both paths.
Basic familiarity with command line or IDE usage, but no prior quantum computing knowledge is required.

Step-by-Step

Create an Azure Quantum workspace
- Go to the Azure portal and sign in.
- Click Create a resource, search for Azure Quantum, and select it.
- Fill in the required fields: choose your subscription, create a new resource group (or use an existing one), give the workspace a name, and select a region (e.g., East US).
- For the Storage account, create a new one (or use an existing). This is used for job results.
- Click Review + create, then Create. Wait for deployment to finish.
Choose your development environment
- Option A (Recommended): VS Code
  - Install VS Code if you don’t have it.
  - Open the Extensions view (Ctrl+Shift+X) and search for Azure Quantum Development Kit. Install it.
- Option B: Azure Quantum Portal
  - Go to your workspace in the Azure portal, and under Operations click Quantum jobs. You’ll be able to write and run Q# code directly in the browser.
Create a new Q# file
- In VS Code, open a folder, then create a new file named Program.qs.
- In the portal, you’ll use the built-in editor.

Write your first quantum program

Copy the following code into your file. This program creates a superposition state using a Hadamard gate and then measures it.

namespace Quantum.Sample {
    open Microsoft.Quantum.Intrinsic;
    open Microsoft.Quantum.Canon;

    @EntryPoint()
    operation RunQuantumProgram() : Result[] {
        // Allocate a qubit
        use qubit = Qubit();

        // Apply Hadamard gate to put the qubit in superposition
        H(qubit);

        // Measure the qubit (collapses to 0 or 1)
        let result = M(qubit);

        // Reset the qubit before releasing it
        Reset(qubit);

        return [result];
    }
}

Connect to your Azure Quantum workspace
- In VS Code, open the command palette (Ctrl+Shift+P) and run Azure Quantum: Connect to Workspace.
- Sign in with your Azure account if prompted, then select your subscription, resource group, and the workspace you created.
- In the portal, you’re already connected.
Submit the job to a simulator
- In VS Code, open the Q# file, then click the Run button (or press F5).
- Choose Simulator as the target (e.g., ionq.simulator or quantinuum.sim).
- In the portal, select the simulator from the dropdown and click Run.
- Wait for the job to complete. You’ll see the result: either Zero or One, randomly (since the qubit is in superposition).
Run on a real quantum computer (optional)
- If you have credits or a paid plan, you can submit to a real hardware provider like IonQ or Quantinuum.
- In VS Code, change the target to a hardware provider (e.g., ionq.qpu).
- In the portal, select the hardware provider from the dropdown.
- Note: Real hardware may have queue times and costs. For learning, the simulator is sufficient.

Common Mistakes

Forgetting to reset the qubit – Always reset a qubit before releasing it, otherwise you’ll get an error.
Using the wrong target – Make sure you’ve selected a simulator, not a hardware provider, for your first run to avoid charges.
Not connecting to the workspace – In VS Code, if you don’t connect, the run button will fail. Always run the connect command first.
Mixing up namespaces – The @EntryPoint() attribute must be on the operation you want to run. If you have multiple operations, only the one with @EntryPoint() will be executed.
Ignoring the output – The result is a Result type, not a string. If you try to print it, use Message($"Result: {result}").

Tips

Start with the simulator – It’s free, fast, and perfect for learning. Real hardware is noisy and has queue times.
Use the Q# documentation – Microsoft has excellent docs for Q#. Refer to them when you want to try more complex operations.
Experiment with more qubits – Modify the program to allocate multiple qubits and apply gates to each. This helps you understand entanglement and superposition.
Use the Azure Quantum portal for quick tests – If you don’t want to set up VS Code, the portal’s built-in editor is a great way to test small snippets.
Check your job history – In the portal, under Quantum jobs, you can see past runs and their results. This is useful for debugging.

Troubleshooting

Error: “No workspace connected” – In VS Code, run Azure Quantum: Connect to Workspace again. Make sure you’re signed in with the correct Azure account.
Error: “Qubit not reset” – Add Reset(qubit); before returning. If you have multiple qubits, reset each one.
Job fails with “Target not found” – You might have selected a target that isn’t available in your region. Check the available targets in your workspace under Providers.
Result is always the same (e.g., always Zero) – This is normal for a single run because measurement is probabilistic. Run the job multiple times or increase the number of shots in the settings to see a distribution.
VS Code can’t find the extension – Ensure you installed the Azure Quantum Development Kit extension, not the older Q# extension. Reload VS Code after install.
Portal shows “No providers” – You need to add a provider (e.g., Microsoft Quantum Simulator) to your workspace. In the workspace, go to Providers and add one.

Frequently Asked Questions

Do I need to know quantum physics to run this?

No. The example above is simple: a Hadamard gate puts the qubit in superposition, and measurement gives a random 0 or 1. You can run it without deep theory, then learn as you go.

Is running on a simulator free?

Yes, Microsoft’s built-in simulator is free. Some third-party simulators may have a free tier, but always check pricing. The example above uses the free simulator.

Can I run this on a real quantum computer?

Yes, but you need to have an Azure Quantum plan that includes hardware credits. The steps are the same; just select a hardware target instead of a simulator. Be aware of costs and queue times.

What is the difference between a simulator and a real quantum computer?

A simulator runs the quantum algorithm on a classical computer, so it’s exact and fast for small circuits. A real quantum computer uses actual qubits, which are noisy and have limited coherence times, but they can run larger circuits that simulators can’t handle.

How do I increase the number of shots (repetitions)?

In the Q# code, you can use a loop to repeat the measurement. Alternatively, in the Azure Quantum portal or VS Code, you can set the shots parameter in the job submission settings. For example, set shots to 100 to see a distribution of results.

What if I want to write a more complex algorithm?

Start by learning the basic gates (H, X, CNOT) and how to use the using block for multiple qubits. Microsoft’s Q# documentation has tutorials and sample code for algorithms like quantum teleportation and Grover’s search.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →