Working with qubits

Qubits are the fundamental object of information in quantum computing. For a general introduction to qubits, see Understanding quantum computing, and to dive deeper into their mathematical representation, see The Qubit.

This article explores how to use and work with qubits in a Q# program.


None of the statements discussed in this article are valid within the body of a function. They are only valid within operations.

Allocating Qubits

Because physical qubits are a precious resource in a quantum computer, part of the compiler's job is to make sure they are being used as efficiently as possible. As such, you need to tell Q# to allocate qubits for use within a particular statement block. You can allocate qubits as a single qubit, or as an array of qubits, known as a register.

Clean qubits

Use the using statement to allocate new qubits for use during a statement block.

The statement consists of the keyword using, followed by a binding enclosed in parentheses ( ) and the statement block within which the qubits are available. The binding follows the same pattern as let statements: either a single symbol or a tuple of symbols, followed by an equals sign =, and either a single value or a matching tuple of initializers.

Initializers are available either for a single qubit, indicated as Qubit(), or an array of qubits, Qubit[n], where n is an Int expression. For example,

using (qubit = Qubit()) {
    // ...
using ((auxiliary, register) = (Qubit(), Qubit[5])) {
    // ...

Any qubits allocated in this way start off in the $\ket{0}$ state. Thus in the previous example, auxiliary is a single qubit in the state $\ket{0}$, and register is in the five-qubit state $\ket{00000} = \ket{0} \otimes \ket{0} \otimes \cdots \otimes \ket{0}$. At the end of the using block, any qubits allocated by that block are immediately deallocated and cannot be used further.


Target machines can reuse deallocated qubits and offer them to other using blocks for allocation. As such, the target machine expects that qubits are in the $\ket{0}$ state immediately before deallocation. Whenever possible, use unitary operations to return any allocated qubits to $\ket{0}$. If need be, you can use the Reset operation, which returns the qubit to $\ket{0}$ by measuring it and conditionally performing an operation based on the result. Such a measurement destroys any entanglement with the remaining qubits and can thus impact the computation.

Borrowed Qubits

Use the borrowing statement to allocate qubits for temporary use, which do not need to be in a specific state.

You can use borrowed qubits as scratch space during a computation. These qubits are generally not in a clean state, that is, they are not necessarily initialized in a known state such as $\ket{0}$. These are often referred to as "dirty" qubits because their state is unknown and can even be entangled with other parts of the quantum computer's memory.

The binding follows the same pattern and rules as the using statement. For example,

borrowing (qubit = Qubit()) {
    // ...
borrowing ((auxiliary, register) = (Qubit(), Qubit[5])) {
    // ...

The borrowed qubits are in an unknown state and go out of scope at the end of the statement block. The borrower commits to leaving the qubits in the same state they were in when they borrowed them; that is, their state at the beginning and the end of the statement block should be the same. Because this state is not necessarily a classical state, in most cases borrowing scopes should not contain measurements.

When borrowing qubits, the system first tries to fill the request from qubits that are in use but not accessed during the body of the borrowing statement. If there aren't enough such qubits, then it allocates new qubits to complete the request.

Among the known use cases of dirty qubits are implementations of multi-controlled CNOT gates that require only very few qubits and implementation of incrementers. For an example of their use in Q#, see Borrowing Qubits Example in this article, or the paper Factoring using 2n+2 qubits with Toffoli based modular multiplication (Haner, Roetteler, and Svore 2017) for an algorithm which utilizes borrowed qubits.

Intrinsic Operations

Once allocated, you can pass a qubit to functions and operations. In some sense, this is all that a Q# program can do with a qubit, as the actions that can be taken are all defined as operations.

This article discusses a few useful Q# operations that you can use to interact with qubits. For more detail about these and others, see Intrinsic Operations and Functions.

First, the single-qubit Pauli operators $X$, $Y$, and $Z$ are represented in Q# by the intrinsic operations X, Y, and Z, each of which has type (Qubit => Unit is Adj + Ctl).

As described in Intrinsic Operations and Functions, think of $X$ and hence of X as a bit-flip operation or NOT gate. You can use the X operation to prepare states of the form $\ket{s_0 s_1 \dots s_n}$ for some classical bit string $s$:

operation PrepareBitString(bitstring : Bool[], register : Qubit[]) : Unit
is Adj + Ctl {
    let nQubits = Length(register);
    for (idxQubit in 0..nQubits - 1) {
        if (bitstring[idxQubit]) {

operation RunExample() : Unit {
    using (register = Qubit[8]) {
            [true, true, false, false, true, false, false, true],
        // At this point, register now has the state |11001001〉.
        // Remember to reset the qubits before deallocation:


Later, you will see more compact ways of writing this operation that do not require manual control flow.

You can also prepare states such as $\ket{+} = \left(\ket{0} + \ket{1}\right) / \sqrt{2}$ and $\ket{-} = \left(\ket{0} - \ket{1}\right) / \sqrt{2}$ by using the Hadamard transform $H$, which is represented in Q# by the intrinsic operation H (also of type (Qubit => Unit is Adj + Ctl)`):

operation PreparePlusMinusState(bitstring : Bool[], register : Qubit[]) : Unit {
    // First, get a computational basis state of the form
    // |s_0 s_1 ... s_n〉 by using PrepareBitString in the earlier example.
    PrepareBitString(bitstring, register);
    // Next, use that |+〉 = H|0〉 and |-〉 = H|1〉 to
    // prepare the desired state.
    for (idxQubit in IndexRange(register)) {


Measurements of individual qubits can be performed in different bases, each represented by a Pauli axis on the Bloch sphere. The computational basis refers to the PauliZ basis, and is the most common basis used for measurement.

Measure a single qubit in the PauliZ basis

Use the M operation, which is a built-in intrinsic non-unitary operation, to measure a single qubit in the PauliZ basis and assign a classical value to the result. M has a reserved return type, Result, which can only take values Zero or One corresponding to the measured states $\ket{0}$ or $\ket{1}$ - indicating that the result is no longer a quantum state.

A simple example is the following operation, which allocates one qubit in the $\ket{0}$ state, then applies a Hadamard operation H to it and measures the result in the PauliZ basis.

operation MeasureOneQubit() : Result {
    // The following using block creates a fresh qubit and initializes it
    // in the |0〉 state.
    using (qubit = Qubit()) {
        // Apply a Hadamard operation H to the state, thereby preparing the
        // state 1 / sqrt(2) (|0〉 + |1〉).
        // Now measure the qubit in Z-basis.
        let result = M(qubit);
        // As the qubit is now in an eigenstate of the measurement operator,
        // reset the qubit before releasing it.
        if (result == One) { X(qubit); }
        // Finally, return the result of the measurement.
        return result;

Measure one or more qubits in specific bases

To measure an array of one or more qubits in specific bases, you can use the Measure operation.

The inputs to Measure are an array of Pauli types (for example, [PauliX, PauliZ, PauliZ]) and an array of qubits.

A slightly more complicated example is given by the following operation, which returns the Boolean value true if all qubits in a register of type Qubit[] are in the state zero when measured in a specified Pauli basis, and which returns false otherwise.

operation MeasureIfAllQubitsAreZero(qubits : Qubit[], pauli : Pauli) : Bool {
    mutable value = true;
    for (qubit in qubits) {
        if (Measure([pauli], [qubit]) == One) {
            set value = false;
    return value;

Note that this example still only performs Measure on individual qubits one at a time, but the operation can be extended to joint measurements on multiple qubits.

Borrowing Qubits Example

There are examples in the canon that use the borrowing keyword, such as the following function MultiControlledXBorrow. If controls denotes the control qubits to add to an X operation, then the number of dirty ancillas added by this implementation is Length(controls)-2.

operation MultiControlledXBorrow ( controls : Qubit[] , target : Qubit ) : Unit
is Adj + Ctl {

    body (...) {
        ... // skipping some case handling here
        let numberOfDirtyQubits = numberOfControls - 2;
        borrowing( dirtyQubits = Qubit[ numberOfDirtyQubits ] ) {

            let allQubits = [ target ] + dirtyQubits + controls;
            let lastDirtyQubit = numberOfDirtyQubits;
            let totalNumberOfQubits = Length(allQubits);

            let outerOperation1 = 
                    numberOfDirtyQubits + 1, 1, 0, numberOfDirtyQubits , _ );
            let innerOperation = 
                    totalNumberOfQubits - 1, totalNumberOfQubits - 2, lastDirtyQubit, _ );
            WithA(outerOperation1, innerOperation, allQubits);
            let outerOperation2 = 
                    numberOfDirtyQubits + 2, 2, 1, numberOfDirtyQubits - 1 , _ );
            WithA(outerOperation2, innerOperation, allQubits);

    controlled(extraControls, ...) {
        MultiControlledXBorrow( extraControls + controls, target );

Note that this example used extensive use of the With combinator, in its form that is applicable for operations that support adjoint, for example, WithA. This is good programming style, because adding control to structures involving With propagates control only to the inner operation. Also note that, in addition to the body of the operation, an implementation of the controlled body of the operation was explicitly provided, rather than resorting to a controlled auto statement. The reason for this is that, because of the structure of the circuit, it is easy to add further controls, which is beneficial compared to adding control to each gate in the body.

It is instructive to compare this code with another canon function MultiControlledXClean which achieves the same goal of implementing a multiply-controlled X operation, however, which uses several clean qubits using the using mechanism.

Next steps

Learn about Control Flow in Q#.