The safest first run is local: install Visual Studio Code and the Microsoft Quantum Development Kit (QDK) extension, create a short Q# Bell-pair program, and run it on the built-in simulator. Only after the code behaves as expected should you create an Azure Quantum workspace, select a current provider target, and submit the same or an equivalent program to an emulator or real quantum processing unit (QPU). You do not need to buy quantum hardware to learn Q# or try Azure Quantum.
What you need before writing code
Azure Quantum has two distinct parts. The QDK and local simulators let you write and test programs on your computer. An Azure Quantum workspace provides cloud targets, including provider simulators, emulators, syntax checkers and, when available to your account and region, real QPUs. Treat those as separate stages rather than assuming that every run goes to hardware.
As an Amazon Associate I earn from qualifying purchases.
Local software requirements
- A current version of Visual Studio Code.
- The Microsoft Quantum Development Kit extension for Visual Studio Code.
- A new file with the
.qsextension. - A Q# operation named
Main, because the guided run command is attached to that operation.
The Q# first-program quickstart displayed a last-updated date of 2024-10-29. Extension commands and language features can change, so use the labels shown by your installed QDK extension rather than relying on an old screenshot.
Cloud requirements for Azure submission
- An Azure account and subscription.
- An Azure Quantum workspace.
- Azure CLI with the
quantumextension when using the Python submission workflow. - Python 3.10 or later for the current Python guidance.
- A provider target enabled in the workspace. The target list differs by region, provider, access plan and date.
A workspace is not a promise that every provider or QPU is available. Targets can be added, renamed, restricted to preview access or removed. Check the workspace’s Providers area immediately before submitting a job.
Run a Bell pair locally in Q#
A Bell pair is the smallest useful demonstration of superposition and entanglement. The first qubit starts in |0⟩. A Hadamard gate, written H, puts it into an equal superposition. A controlled-NOT, written CNOT, flips the second qubit when the first is |1⟩. Ideally, the two-qubit state then has equal probability of |00⟩ and |11⟩.
1. Create the Q# file
- Open Visual Studio Code.
- Install or enable the Microsoft Quantum Development Kit extension.
- Create a new file named, for example,
BellPair.qs. - Paste the following operation into the file:
import Std.Diagnostics.*;
operation Main() : (Result, Result) {
use (q1, q2) = (Qubit(), Qubit());
H(q1);
CNOT(q1, q2);
DumpMachine();
let (m1, m2) = (M(q1), M(q2));
Reset(q1);
Reset(q2);
return (m1, m2);
}use allocates two qubits and ensures they are released correctly. H(q1) creates the superposition, and CNOT(q1, q2) entangles the pair. DumpMachine() prints the simulated state before measurement. The measurements return Zero or One; the two reset operations return each qubit to |0⟩ before the operation ends.
2. Start the local simulator
- Place the cursor inside
Main, or use the Run command displayed above the operation by the QDK extension. - Run the operation with
Ctrl+F5if that shortcut is shown by your installation. - Read the state dump and the returned pair in the terminal or output panel.
The ideal state dump shows amplitudes corresponding to |00⟩ and |11⟩, each with 50% probability. A single measurement is expected to return either (Zero, Zero) or (One, One). Repeating the run can produce a different pair because measurement is probabilistic, but the two values should remain correlated in the ideal simulation.
3. Interpret the result correctly
- Superposition: before measurement, the state contains both possible computational outcomes with nonzero amplitude.
- Entanglement: measuring one qubit determines the corresponding result of the other in this ideal Bell state.
- No practical speedup: this two-qubit demonstration explains quantum concepts; it does not prove an advantage for a business workload.
If the output appears in a different order, check how the simulator labels qubit registers and basis states. The physical meaning is the same when the two measured bits agree.
Why local simulation should come before cloud hardware
A local simulator gives immediate feedback without an Azure subscription, queue, provider quota or usage charge. It is the right place to catch syntax errors, incorrect register order, missing resets and mistaken assumptions about measurement. A simulator cannot reproduce every hardware effect, however. Real devices have noise, connectivity limits, calibration changes and finite queues.
Rank #2
Azure Quantum also exposes provider-hosted simulators and emulators. Microsoft describes these as available to Azure Quantum users and suitable for testing Q# programs before real hardware. Examples listed in the provider documentation include an IonQ simulator, Quantinuum emulators, Pasqal emulators and Rigetti’s QVM. Some simulator targets are free, but the current target page and workspace determine the applicable access rules.
| Execution stage | What it is good for | What it does not establish |
|---|---|---|
| Local Q# simulator | Fast syntax and logic checks; learning gates and measurement | How a particular provider’s hardware noise or queue behaves |
| Provider simulator or emulator | Testing a cloud submission format and provider-specific workflow | Actual QPU performance or production availability |
| Real QPU | Observing results from a physical quantum processor | A guaranteed advantage, stable calibration or fixed price |
Use Python and notebooks when your workflow grows
Visual Studio Code and Q# are the shortest path to a first run. Python becomes useful when you need notebooks, data preparation, repeated jobs or one program that submits Q#, OpenQASM, Qiskit, Cirq or PennyLane workloads. The current Azure submission guidance lists Python 3.10 or later.
Free tools Windows power users keep installed
One-click scans. No signup required.
Install the QDK Python package
python -m pip install "qdk[azure]"
az extension add --upgrade -n quantumFor notebook work, install the Jupyter extras specified by the setup guidance in addition to the Azure extra. Optional Qiskit and Cirq extras are appropriate only when you intend to use those frameworks. Keep the installation in a virtual environment so that QDK, notebook and quantum-framework versions do not interfere with another project.
Authenticate and connect to a workspace
- Sign in to Azure with
az login. - If the account has more than one subscription, select the intended subscription with the Azure CLI subscription command.
- Create a workspace in the Azure portal, or identify an existing workspace.
- Copy the workspace resource ID from the portal.
- Construct a
qdk.azure.Workspaceobject with that resource ID in Python. - Call
workspace.get_targets()to list the targets that this workspace can currently see.
A minimal connection pattern is conceptually:
from qdk.azure import Workspace
workspace = Workspace(
resource_id="<the workspace resource ID>"
)
targets = workspace.get_targets()
for target in targets:
print(target)Replace the resource-ID text with the value copied from your own workspace. Do not treat a target name copied from an old tutorial as authoritative; select from the object returned for your workspace.
Create an Azure Quantum workspace
Portal workflow
- Open the Azure portal and choose the option to create an Azure Quantum workspace.
- Select the subscription, resource group, region and workspace name required by your organization.
- Review the provider choices and any access or pricing information presented during creation.
- Deploy the workspace.
- Open the completed workspace and copy its resource ID for CLI or Python use.
Region matters. Provider availability is not uniform across Azure regions, and some offerings are private preview or subject to separate approval. The provider target list shown as last updated on 2026-04-23 is a useful date marker, not a permanent inventory. The workspace’s Providers tab is the operational source of truth.
What to record before submitting
- The exact provider and target name displayed in the workspace.
- Whether the target is a simulator, emulator, syntax checker, production QPU or private preview.
- The supported language or input format.
- Qubit capacity and any circuit-size or shot restrictions.
- Queue or access-plan requirements.
- The usage unit, price and remaining quota.
Submit a program to a provider simulator
After local testing, choose a simulator target from workspace.get_targets() or the workspace Providers tab. Provider simulators are a lower-risk bridge between a local run and a QPU: they exercise authentication, job submission and result retrieval without exposing the circuit to physical noise or a hardware queue.
Recommended Free Tools
- Confirm that the target is available to your subscription and region.
- Confirm that it accepts the language or format of your program.
- Set a small shot count while learning.
- Submit the job through the QDK or the provider’s documented integration.
- Wait for completion and retrieve the histogram or measurement results.
- Compare the distribution with the local Bell-pair expectation: matching bit pairs should dominate an ideal simulation.
If a provider simulator rejects the Q# source, use the provider’s supported Q# integration or convert the circuit to an accepted format such as OpenQASM where appropriate. A syntax checker can confirm that a circuit is structurally valid, but it is not evidence that a QPU will execute it successfully.
Submit to real quantum hardware
Real-hardware execution adds three requirements beyond local simulation: an authenticated Azure account, a workspace with a usable provider target, and a submission that complies with that target’s current access and quota rules. The available providers can include IonQ, Pasqal, Quantinuum and Rigetti, but the exact target names, qubit counts and access plans change.
Hardware submission checklist
- Run the program locally and verify the expected logic.
- Run a small test on a provider simulator or emulator when one is available.
- Open the Providers tab immediately before submission.
- Check whether the target is production, preview, emulator or syntax-only.
- Check the target’s supported gate set, circuit width, shot limits and queue conditions.
- Confirm the estimated usage and remaining quota.
- Submit a small number of shots first, then increase the experiment only if the results are useful.
Hardware results will not look exactly like the ideal local distribution. A Bell-pair circuit can show mismatched outcomes because of gate, readout and transport errors. Noise is a property of the execution environment, not automatically a bug in your Q# code.
Understand Azure Quantum pricing and quotas
There is no single Azure Quantum price for every job. Providers define their own billing units and rates. The pricing page shown as last updated on 2025-12-23 describes several different models:
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →| Provider family | Usage model described by Azure | What to verify before a job |
|---|---|---|
| IonQ | AQT or gate-shot based measurement | Current target rate, shot count, gate count and any minimum charge |
| Quantinuum | HQC or eHQC units | Whether the target is hardware or emulator and the applicable unit rate |
| Pasqal | Execution-time pricing | Time charged, minimum duration and target-specific access rules |
| Rigetti | Execution-time pricing | Queue, minimum execution interval and current target rate |
The table identifies billing concepts, not universal prices. Rates and availability can change, so read the price shown for the selected target in your account before submitting. A free simulator does not imply that a related QPU is free.
Set a quota guardrail
- Open the workspace in the Azure portal.
- Go to Operations and then Quotas.
- Review the provider-specific limits and remaining allowance.
- Keep initial shot counts and circuit repetitions small.
- Stop and investigate if a job would consume an unexpectedly large allowance.
Quotas are provider-specific safeguards intended to prevent accidental overages. They are not interchangeable with price estimates: a job can fit within a quota while still incurring a charge, or be blocked by a quota before a paid execution is possible.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Common first-run failures and fixes
The Run command is missing
- Confirm that the file ends in
.qs. - Confirm that the QDK extension is installed and enabled for the current Visual Studio Code profile.
- Make sure the operation is named
Mainand has no syntax error above it. - Reload the Visual Studio Code window after installing or updating the extension.
The program returns different results each time
That is expected for a measured superposition. Repeat the run many times and inspect whether the two bits remain correlated. A single result is not a probability estimate.
The state dump is confusing
Read the basis-state labels and probabilities rather than treating the text layout as a circuit diagram. The Bell state should assign approximately equal weight to the matching states and little or no weight to the mismatched states in an ideal simulation.
Azure CLI cannot find the quantum extension
Run az extension add --upgrade -n quantum, then verify that the CLI is logged into the intended tenant and subscription. If multiple installations of Azure CLI exist, make sure the command is running in the same environment where you will submit the job.
Best Value
No suitable target appears
- Check the workspace region and subscription.
- Open the Providers tab instead of relying on a copied target name.
- Look for preview or approval requirements.
- Confirm that your program’s language and circuit size match the target.
- Check whether a provider is temporarily unavailable or your quota is exhausted.
A hardware job is rejected or remains queued
Recheck the target’s current status, queue policy, access plan, circuit limits and quota. Hardware queues are not equivalent to local execution time. Cancel or reduce a job that is larger than necessary for the question you are asking.
Hardware results are noisy
Compare the hardware distribution with the local and provider-simulator baselines. Verify that the circuit uses gates supported efficiently by the selected target, increase shots only after confirming the job is affordable, and record the target name and submission date because calibration changes over time.
A practical progression from first program to useful experiment
- Learn the syntax locally: run the two-qubit Bell pair and change one gate at a time.
- Build confidence statistically: repeat the circuit and collect enough samples to see the correlated distribution.
- Use a cloud simulator: validate authentication, target selection and result retrieval.
- Measure resource needs: use Q# tooling to estimate whether a larger application fits a desired architecture. Microsoft describes the Quantum resource estimator as a way to compare qubit technologies and assess architectural decisions.
- Try a small QPU job: use the smallest circuit and shot count that answers your question.
- Document the run: save the provider, target, region, date, circuit, shot count, result distribution and cost or quota impact.
This progression separates software correctness from hardware behavior. It also makes a failed cloud job easier to diagnose: you can tell whether the problem is Q# syntax, authentication, target compatibility, queue access or physical noise.
Further learning without buying hardware
Microsoft’s Azure Quantum learning path is listed as six modules, about 3 hours 20 minutes and 4,500 XP in the 2026 material. It is a reasonable next step after the Bell-pair exercise if you want guided practice with quantum concepts, Q# and Azure workflows. The learning path and local simulators allow substantial study without purchasing a quantum computer.
The broader Q# workflow can include writing programs, simulating their behavior, estimating resource requirements and running them on real hardware. Hardware access is therefore the final execution option, not a prerequisite for learning the language.
What your first successful run proves
A successful local Bell-pair run proves that your Q# environment can compile and simulate a two-qubit operation and that you understand the relationship between gates and measurement. A successful cloud-simulator run additionally proves that your identity, workspace and target selection work together. Only a hardware run demonstrates execution on a physical device, and even then the result is a sample from a noisy, time-dependent system rather than a general performance claim.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →
