--- title: capi (latest version) description: API reference for qiskit.capi in the latest version of qiskit source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/qiskit/capi --- # C API interface from Python `qiskit.capi` This module provides Python-space interactions with Qiskit’s public C API. For documentation on the C API itself, see [Qiskit C API](/docs/api/qiskit-c/). ## Build-system interaction The Python package [`qiskit`](/docs/api/qiskit/index#module-qiskit "qiskit") contains all of the Qiskit C API header files, and a compiled shared-object library that includes all of the C-API functions. You can access the locations of these two objects with the functions [`get_include()`](#qiskit.capi.get_include "qiskit.capi.get_include") and [`get_lib()`](#qiskit.capi.get_lib "qiskit.capi.get_lib") respectively. > **Warning** > > You typically *should not* link directly against the output of [`get_lib()`](#qiskit.capi.get_lib "qiskit.capi.get_lib"), unless you know what you are doing. In particular, directly linking against this object is not a safe way to build a distributable Python extension module that uses Qiskit’s C API. > > However, if you understand all the caveats of direct linking, you can use the function to get the location of the library. ### get\_include `qiskit.capi.get_include()` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/capi/__init__.py#L101-L119) Get the directory containing the `qiskit.h` C header file and the internal `qiskit/*.h` auxiliary files. When using Qiskit as a build dependency, you typically want to include this directory on the include search path of your compiler, such as: ```bash qiskit_include=$(python -c 'import qiskit.capi; print(qiskit.capi.get_include())') gcc -I "$qiskit_include" my_bin.c -o my_bin ``` The location of this directory within the Qiskit package data is not fixed, and may change between Qiskit versions. You should always use this function to retrieve the directory. **Returns** an absolute path to the package include-files directory. **Return type** [str](https://docs.python.org/3/library/stdtypes.html#str) ### get\_lib `qiskit.capi.get_lib()` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/capi/__init__.py#L122-L140) Get the path to a shared-object library that contains all the C-API exported symbols. > **Warning** > > You typically *should not* link directly against this object. In particular, directly linking against this object is not a safe way to build a Python extension module that uses Qiskit’s C API. You can, if you choose, use [`ctypes`](https://docs.python.org/3/library/ctypes.html#module-ctypes) to access the C API symbols contained in this object, though beware that the C-API types declared in the header file are not interchangeable with the Python objects that correspond to them. The location and name of this file within the Qiskit package data is not fixed, and may change between Qiskit versions. **Returns** an absolute path to the shared-object library containing the C-API exported symbols. **Return type** [str](https://docs.python.org/3/library/stdtypes.html#str) ## Native bindings to the C API Additionally, this module contains [`ctypes`](https://docs.python.org/3/library/ctypes.html#module-ctypes) bindings to all Qiskit C API types and functions. These are available as module attributes on [`qiskit.capi`](#module-qiskit.capi "qiskit.capi") with the same name as they have in the C API. For example, `qiskit.capi.qk_circuit_new` corresponds to [`qk_circuit_new()`](/docs/api/qiskit-c/qk-circuit#qk_circuit_new "qk_circuit_new"). ### qiskit.capi.LIB Type: `ctypes.PyDLL` A [`ctypes`](https://docs.python.org/3/library/ctypes.html#module-ctypes) wrapper around the library containing the Qiskit C API. This is provided for completeness, though you can access all the functions, structs and enumerations directly from the [`qiskit.capi`](#module-qiskit.capi "qiskit.capi") module object. ### Structs Concrete `struct` types used in the C API are declared as corresponding [`ctypes.Structure`](https://docs.python.org/3/library/ctypes.html#ctypes.Structure) types with a complete [`_fields_`](https://docs.python.org/3/library/ctypes.html#ctypes.Structure._fields_) attribute. These can be instantiated and inspected directly. Opaque pointers are represented by a [`ctypes.Structure`](https://docs.python.org/3/library/ctypes.html#ctypes.Structure) type with no [`_fields_`](https://docs.python.org/3/library/ctypes.html#ctypes.Structure._fields_) attribute set, and cannot be instantiated. They are typically returned from functions wrapped in a `ctypes.POINTER` type wrapper. ### Enums In places where the C API has an enumeration, this module declares a Python [`enum.Enum`](https://docs.python.org/3/library/enum.html#enum.Enum) whose values are a corresponding [`ctypes`](https://docs.python.org/3/library/ctypes.html#module-ctypes) primitive integer type. The Python-space [`Enum`](https://docs.python.org/3/library/enum.html#enum.Enum) type object is still a wrapping Python object, so [`ctypes`](https://docs.python.org/3/library/ctypes.html#module-ctypes) functions that return an enumeration will return the raw numeric value, not the value in the [`Enum`](https://docs.python.org/3/library/enum.html#enum.Enum). The Python-space [`Enum`](https://docs.python.org/3/library/enum.html#enum.Enum) objects are declared for convenience in constructing calls. ### Functions All the public library functions in the Qiskit C API are fully typed, and re-exported in the module root with the same name as they have in C. You can also access the functions from [`LIB`](#qiskit.capi.LIB "qiskit.capi.LIB"), if you prefer. Note that header-only functions, such as [`qk_import()`](/docs/api/qiskit-c/config#qk_import "qk_import"), are not exported because they are not part of the C API library object.