---
id: numpy-quaternion
version: "2024.0.13"
license: MIT
license_treatment: permissive
maintenance: aging
---

# numpy-quaternion — Add a quaternion dtype to NumPy

License: permissive · Maintenance: aging · Downloads: 1.1M/mo

## What it is and what it does

numpy-quaternion extends NumPy with a native quaternion dtype, allowing quaternions to be used directly in NumPy arrays and operations. Quaternions are represented as a scalar (w) followed by three imaginary components (x, y, z), stored as double-precision floats. The package implements standard ufuncs (add, multiply, exp, log, conjugate, etc.) that run efficiently on quaternion arrays, and provides conversion functions to rotate between quaternion, rotation matrix, rotation vector, Euler angle, and spherical coordinate representations.

The package is built on NumPy and scipy, making it suitable for scientific and engineering applications that need 3D rotations or orientation calculations. Installation typically requires a C compiler, though prebuilt wheels are available for Python 3.10–3.13 on macOS, Linux, and Windows. The code is production-stable and actively maintained, with comprehensive documentation and examples.

Use it for:

- Represent and manipulate 3D rotations in robotics, aerospace, or computer graphics applications
- Perform batch quaternion arithmetic on large arrays without Python loops
- Convert between rotation representations (matrices, Euler angles, rotation vectors) for different algorithms
- Compute exponentials, logarithms, and other transcendental functions on quaternion arrays
- Store orientation data compactly in NumPy arrays while maintaining numerical precision

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Adds a quaternion dtype to NumPy, enabling efficient quaternion arithmetic and array operations with native NumPy integration.

Yes, if you need quaternion support in NumPy-based scientific code. The package is production-stable, actively maintained, MIT-licensed, and has no known vulnerabilities. Install friction is moderate due to C compilation, but prebuilt wheels are available for common platforms. Not necessary if you only need basic quaternion math or prefer pure-Python alternatives.

## Install

pip install numpy-quaternion
uv add numpy-quaternion
poetry add numpy-quaternion

## Installing numpy-quaternion

Before you install: Medium install friction due to C compilation requirement. Package is actively maintained with recent releases; last commit 2025-12-15. Supports Python 3.10–3.13 with prebuilt wheels for common platforms (macOS, Linux x86_64, ARM, Windows).

License in practice: MIT license permits free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart:

import numpy as np
import quaternion

q1 = np.quaternion(1, 2, 3, 4)
q2 = np.quaternion(5, 6, 7, 8)
result = q1 * q2

a = np.array([q1, q2])
exponentials = np.exp(a)

Requires a working C compiler for pip installation; prebuilt wheels available for common platforms. Python 3.10–3.13 required.

Verify before relying:

- Whether scipy is used at runtime or only as a build/test dependency
- Performance characteristics compared to pure-Python quaternion libraries
- Specific use cases in astronomy or physics applications beyond rotation representation

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: aging
- Downloads: 1.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

quaternion math numpy, quaternion dtype, rotation quaternions, quaternion arrays, 3d rotation representation, quaternion operations, numpy quaternion dtype, rotation-math, numpy-extension, 3d-graphics

[View on SkillFed](https://skillfed.io/packages/numpy-quaternion) · [View on PyPI](https://pypi.org/project/numpy-quaternion/)