Install & Compatibility
Where this runs
tested against v0.9.9 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.256s · 89.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.6s · import 0.252s · 86MB
89MB installed
● package 89MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Quaternion
✓ from pyquaternion import Quaternion
This quickstart demonstrates creating a quaternion for a 90-degree rotation around the Y-axis and applying it to a vector. It also shows basic spherical linear interpolation (SLERP) between two quaternions.
import pyquaternion
import numpy as np
# Create a quaternion representing a rotation of +90 degrees about the positive y-axis
my_quaternion = pyquaternion.Quaternion(axis=[0, 1, 0], degrees=90)
# Define a vector to rotate
my_vector = np.array([0., 0., 4.])
# Rotate the vector
my_rotated_vector = my_quaternion.rotate(my_vector)
print(f"Original Vector: {my_vector}")
print(f"Performing rotation of {my_quaternion.degrees:.1f} degrees about {my_quaternion.axis}")
print(f"Rotated Vector: {my_rotated_vector}")
# Example of interpolation
null_quaternion = pyquaternion.Quaternion(axis=[0, 1, 0], angle=0)
print("\nInterpolated Rotations:")
for i, q in enumerate(pyquaternion.Quaternion.intermediates(null_quaternion, my_quaternion, 3, include_endpoints=True)):
interpolated_vector = q.rotate(my_vector)
print(f" Step {i}: rotated by {q.degrees:.1f} deg about {q.axis}, resulting in {interpolated_vector}")
Debug
Known issues
gotchaThe library has not seen a new release since October 2020. While it may be stable, users should be aware that active feature development or rapid bug fixes are unlikely.fixReview the GitHub issues and pull requests for any pending critical fixes. Consider the project's long-term maintenance status if this is a concern for new projects.
affects: 0.9.9 and potentially earlier versions
gotchaWhen a quaternion represents a null rotation (angle is 0), its rotation axis is geometrically undefined. `pyquaternion` defaults this axis to `[0, 0, 0]`, which might be unexpected or cause issues in downstream calculations if not handled explicitly. The `get_axis(undefined=[...])` method allows specifying a custom default.fixWhen dealing with potentially null rotations, explicitly check `my_quaternion.angle` and, if zero, use `my_quaternion.get_axis(undefined=[your_preferred_default])` to control the returned axis vector.
affects: All versions
gotchaSome methods, such as `angle`, `integrate`, and `normalised`, implicitly normalize the Quaternion object to a unit quaternion if it is not already one. While often desirable for rotations, this automatic normalization might be an unexpected side-effect if you are working with non-unit quaternions and expect their norm to be preserved.fixBe aware of methods that implicitly normalize. If working with non-unit quaternions and their norm is critical, explicitly check the `is_unit` property or re-normalize manually when required, rather than relying on implicit behavior.
affects: All versions
gotchaAn older GitHub issue (#21, dating from 2018/2021) indicated potential sign-flipping issues with the i, j, k components during matrix-to-quaternion conversions. While there was a response from the maintainer, the issue's long-standing open status might suggest it was not fully resolved in the latest release or required specific workarounds.fixThoroughly validate matrix-to-quaternion conversions, especially if integrating with other libraries or systems that use different quaternion conventions. Cross-verify results with known correct transformations for critical paths. If issues persist, consider manually implementing or adjusting for potential sign differences.
affects: Potentially all versions up to 0.9.9
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pyquaternion'
The 'pyquaternion' package is not installed in the current Python environment or the environment is not active.
fixpip install pyquaternion
TypeError: 'float' object is not callable
The 'norm' attribute of a Quaternion object is a float representing its magnitude, not a method, so it cannot be called.
TypeError: unsupported operand type(s) for *: 'Quaternion' and 'list'
Attempting to multiply a Quaternion object directly with a Python list. Quaternion multiplication is defined for other Quaternions or scalar values, or for rotating vectors using the 'rotate()' method.
fixrotated_vector = q.rotate(numpy.array([x, y, z]))
TypeError: 'Quaternion' object is not subscriptable
Quaternion objects do not support direct indexing like lists or arrays to access components. Components are accessed via attributes (e.g., q.w, q.x) or the 'elements' property.
fixw_component = q.w # Access individual component
all_elements = q.elements # Get elements as a NumPy array
Upgrade
Version history
0.9.9latest on PyPI · released Oct 5, 2020
Audit
Dependencies
numpyrequiredRequired for array and matrix representation and numerical operations, automatically installed.