Skip to main contentIBM Quantum Documentation
You are viewing the API reference for an old version of Qiskit SDK. Switch to latest version


dump(programs, file_obj, metadata_serializer=None)

GitHub(opens in a new tab)

Write QPY binary data to a file

This function is used to save a circuit to a file for later use or transfer between machines. The QPY format is backwards compatible and can be loaded with future versions of Qiskit.

For example:

from qiskit.circuit import QuantumCircuit
from qiskit import qpy
qc = QuantumCircuit(2, name='Bell', metadata={'test': True})
qc.h(0), 1)

from this you can write the qpy data to a file:

with open('bell.qpy', 'wb') as fd:
    qpy.dump(qc, fd)

or a gzip compressed file:

import gzip
with'bell.qpy.gz', 'wb') as fd:
    qpy.dump(qc, fd)

Which will save the qpy serialized circuit to the provided file.


  • programs (Union[List[Union[QuantumCircuit, ScheduleBlock]], QuantumCircuit, ScheduleBlock]) – QPY supported object(s) to store in the specified file like object. QPY supports QuantumCircuit and ScheduleBlock. Different data types must be separately serialized.
  • file_obj (BinaryIO) – The file like object to write the QPY data too
  • metadata_serializer (Optional[Type[JSONEncoder]]) – An optional JSONEncoder class that will be passed the .metadata attribute for each program in programs and will be used as the cls kwarg on the json.dump()` call to JSON serialize that dictionary.


  • QpyError – When multiple data format is mixed in the output.
  • TypeError – When invalid data type is input.
Was this page helpful?
Report a bug or request content on GitHub.