Install & Compatibility
Where this runs
tested against v5.2.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
build_error
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 15.2s · import 4.741s · 651MB
681MB installed
● package 681MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
qutip
✓ import qutip as qt
✗ from qutip import *
While `from qutip import *` is shown in some older tutorials, `import qutip as qt` is generally recommended for clarity and to avoid polluting the namespace.
Qobj
✓ from qutip import Qobj
# or qt.Qobj if 'import qutip as qt' is used
Qobj is the core class for quantum objects (states and operators).
This quickstart demonstrates creating basic quantum objects (ket states and operators) and performing fundamental operations like applying an operator to a state and calculating an expectation value.
import qutip as qt
# Create a basis state |0> for a two-level system
ket0 = qt.basis(2, 0)
print(f"Ket |0>:\n{ket0}")
# Create a Pauli sigma-x operator
sigmax = qt.sigmax()
print(f"Sigma-x operator:\n{sigmax}")
# Apply the operator to the state
ket1 = sigmax * ket0
print(f"Sigma-x applied to |0> (gives |1>):\n{ket1}")
# Calculate expectation value
exp_val = qt.expect(sigmax, ket0)
print(f"Expectation value of sigma-x in |0>: {exp_val}")
Debug
Known issues
breakingQuTiP 5.x introduced significant breaking changes from 4.x, particularly in the core `Qobj`, `QobjEvo`, and solver implementations.fixConsult the official migration guide for QuTiP 4 to 5. Key changes include how `QobjEvo` attributes are accessed, the return type of bra-ket multiplication, and explicit conversion to NumPy arrays using `Qobj.full()` instead of implicit conversion.
affects: 4.x users migrating to 5.x
breakingThe `qutip.qip` and `qutip.control` modules have been moved out of the core `qutip` library into separate packages (`qutip-qip`, `qutip-qtrl`, `qutip-qoc`).fixInstall the respective standalone packages (e.g., `pip install qutip-qip`) and update import statements. For example, `from qutip.qip import QubitCircuit` becomes `from qutip_qip import QubitCircuit` or `from qutip.qip import QubitCircuit` after installing `qutip-qip`.
affects: 5.0.0 and later
gotchaUsing an insufficient number of states (truncation) in simulations, especially for time-evolution of open quantum systems or harmonic oscillators, can lead to inaccurate or incorrect results at later times.fixAlways verify convergence by increasing the number of states and observing if the results change significantly. Plotting the error as a function of system size can help determine an appropriate truncation.
affects: All versions
gotchaThe `steadystate()` solver in older QuTiP versions sometimes produced pivot errors for systems with ill-defined steady states (e.g., dissipationless dark states or multiple steady states). While newer versions might avoid the explicit error, they could silently return a 'nonsense' result.fixCarefully examine the physical validity of results from `steadystate()` if the system is known to have such pathologies. Consider checking the eigenvalues of the Liouvillian for multiple zero eigenvalues, though this can be computationally costly.
affects: All versions, more pronounced as silent failure in newer versions (5.x)
Errors
Common errors & fixes
TypeError: 'complex' object is not subscriptable
In QuTiP v5.x, the multiplication of a bra `Qobj` with a ket `Qobj` now returns a scalar (a Python `complex` number) instead of a zero-dimensional `Qobj`. Attempting to index this scalar (e.g., `result[0][0]`) will raise this error.
fixIf your code expects a `Qobj` and attempts to index it, remove the indexing. The result of `bra * ket` is directly the scalar complex number. If you need the complex value, use it directly (e.g., `value = bra * ket`).
AttributeError: 'QobjEvo' object has no attribute 'ops' / 'cte'
In QuTiP 5.x, direct access to individual Hamiltonian elements through `QobjEvo.ops` and `QobjEvo.cte` attributes has been removed as part of the core redesign.
fixInstead of direct attribute access, evaluate the `QobjEvo` object at a specific time step by calling it like a function, e.g., `quobjevo(t)`. Most metadata (dims, shape) can be obtained from its properties directly.
Object passed to assert_allclose is not an array.
QuTiP 5.x no longer implicitly converts `Qobj` instances to NumPy arrays using `numpy.array(qobj)`. This change prevents silent data type transformations.
fixWhen comparing `Qobj` instances or their NumPy array representations using functions like `numpy.testing.assert_allclose`, explicitly convert the `Qobj` to a NumPy array using the `.full()` method: `qobj.full()`.
Upgrade
Version history
5.3.0latest on PyPI · released May 22, 2026
Audit
Dependencies
numpyrequiredNumerical backend
scipyrequiredNumerical backend
cythonrequiredNumerical backend for performance
matplotlibrequiredGraphical output and visualization
qutip-qipoptionalFor quantum information processing functionality (moved from core library in v5)
qutip-qtrloptionalFor quantum optimal control (legacy, `qutip-qoc` is newer)
qutip-jaxoptionalJAX backend for QuTiP (provides JAX-based data formats)