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


load(file_obj, metadata_deserializer=None)

GitHub(opens in a new tab)

Load a QPY binary file

This function is used to load a serialized QPY Qiskit program file and create QuantumCircuit objects or ScheduleBlock objects from its contents. For example:

from qiskit import qpy
with open('bell.qpy', 'rb') as fd:
    circuits = qpy.load(fd)

or with a gzip compressed file:

import gzip
from qiskit import qpy
with'bell.qpy.gz', 'rb') as fd:
    circuits = qpy.load(fd)

which will read the contents of the qpy and return a list of QuantumCircuit objects or ScheduleBlock objects from the file.


  • file_obj (BinaryIO) – A file like object that contains the QPY binary data for a circuit or pulse schedule.
  • metadata_deserializer (Optional[Type[JSONDecoder]]) – An optional JSONDecoder class that will be used for the cls kwarg on the internal json.load call used to deserialize the JSON payload used for the .metadata attribute for any programs in the QPY file. If this is not specified the circuit metadata will be parsed as JSON with the stdlib json.load() function using the default JSONDecoder class.

Return type

List[Union[QuantumCircuit, ScheduleBlock]]


The list of Qiskit programs contained in the QPY data. A list is always returned, even if there is only 1 program in the QPY data.


  • QiskitError – if file_obj is not a valid QPY file
  • TypeError – When invalid data type is loaded.
Was this page helpful?
Report a bug or request content on GitHub.