Install

Prerequisites

• Managed workflows enabled on your IBM Quantum® Platform instances. Contact your administrator to enable it.
• An API key and the CRN of your instance. See Find your access credentials.
• Python 3.10 or later, in an active virtual environment. See Install Qiskit for how to set up an environment.

Quick start with AI skills

You can use the AI skills in the Qiskit Function templates repository to help you install qiskit-ibm-catalog, package your existing local code, and deploy it as a managed workflow.

Install the client package

Install the qiskit-ibm-catalog package:

pip install qiskit-ibm-catalog

This command also installs qiskit-serverless, qiskit, and qiskit-ibm-runtime as dependencies. You do not need to install qiskit-serverless separately. The examples in these guides require qiskit-ibm-catalog 0.22.0 or later, which installs qiskit-serverless 0.38 and qiskit-ibm-runtime 0.51.

You use two of these packages directly, in different places:

• qiskit-ibm-catalog is the client that you use on your local computer to upload workflows, run them, and get their results.
• qiskit-serverless runs inside your workflow code. It provides helpers such as get_arguments(), update_status(), and save_result().

Update the client package

Because managed workflows is in beta, the client package changes often. To check which version you have, run the following command:

pip show qiskit-ibm-catalog

Or, in Python:

import qiskit_ibm_catalog

print(qiskit_ibm_catalog.__version__)

To update to the latest version, run the following command:

pip install --upgrade qiskit-ibm-catalog

If the new version of qiskit-ibm-catalog requires a newer version of qiskit-serverless, this command also updates qiskit-serverless.

Authenticate

The managed workflows client uses the same credentials as qiskit-ibm-runtime. If you already saved an account with QiskitRuntimeService.save_account(), the client loads your default saved account, and you can skip to Verify your setup.

If you have not saved an account, save your API key and instance CRN one time in a trusted environment:

from qiskit_ibm_catalog import ManagedWorkflowClient

ManagedWorkflowClient.save_account(
    token="<your-api-key>",
    instance="<your-instance-crn>",
)

This method writes your credentials to the same file as QiskitRuntimeService.save_account(). The client uses the ibm_quantum_platform channel by default, so you do not need to set channel. To save more than one account, set name, and pass the same name when you create the client.

For more options, such as saving several accounts or selecting an instance automatically, see Save your login credentials. If you work on a public computer or another untrusted environment, do not save your credentials. Instead, follow Initialize the service in an untrusted environment.

Verify your setup

Connect to managed workflows with your saved account, and list the workflows that you uploaded:

from qiskit_ibm_catalog import ManagedWorkflowClient

client = ManagedWorkflowClient()
client.list()

If you have not uploaded a workflow yet, the output is an empty list ([]). If you see an authentication error, the client did not find valid credentials. Check the account that you saved in the Authenticate section.

Next steps