Install & Compatibility
Where this runs
tested against v0.11.2 · 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.920 runs
installs and imports cleanly · install 0.0s · import 1.413s · 233.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 7.6s · import 1.350s · 225MB
233MB installed
● package 233MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
KalmanFilter
✓ from pykalman import KalmanFilter
UnscentedKalmanFilter
✓ from pykalman import UnscentedKalmanFilter
Used for non-linear state estimation problems.
This quickstart demonstrates the basic usage of `KalmanFilter` to estimate states from noisy measurements. It defines a simple linear system, generates synthetic data, and then applies the `filter` and `smooth` methods to estimate the underlying states.
import numpy as np
from pykalman import KalmanFilter
# Define the parameters of a simple linear system
transition_matrices = [[1, 1], [0, 1]] # State transition matrix
observation_matrices = [[1, 0]] # Observation matrix (we observe position only)
transition_covariance = np.eye(2) * 0.1 # Small process noise
observation_covariance = np.eye(1) * 1.0 # Larger observation noise
initial_state_mean = [0, 1] # Initial state (position=0, velocity=1)
initial_state_covariance = np.eye(2) * 1.0 # Initial uncertainty
# Create a Kalman Filter instance
kf = KalmanFilter(
transition_matrices=transition_matrices,
observation_matrices=observation_matrices,
transition_covariance=transition_covariance,
observation_covariance=observation_covariance,
initial_state_mean=initial_state_mean,
initial_state_covariance=initial_state_covariance
)
# Generate some noisy 'measurements' for a simple linear motion
n_timesteps = 50
true_states = np.zeros((n_timesteps, 2))
measurements = np.zeros((n_timesteps, 1))
true_states[0] = initial_state_mean
for t in range(1, n_timesteps):
true_states[t] = np.dot(transition_matrices, true_states[t-1]) + np.random.multivariate_normal([0, 0], transition_covariance)
measurements[t] = np.dot(observation_matrices, true_states[t]) + np.random.normal(0, np.sqrt(observation_covariance[0,0]))
# Use the Kalman Filter to estimate the states from measurements
(filtered_state_means, filtered_state_covariances) = kf.filter(measurements)
(smoothed_state_means, smoothed_state_covariances) = kf.smooth(measurements)
print("First 5 filtered state means (position, velocity):")
print(filtered_state_means[:5])
print("\nFirst 5 smoothed state means (position, velocity):")
print(smoothed_state_means[:5])
Debug
Known issues
breakingPython 3.8 (and earlier) is no longer supported as of v0.10.0, and Python 3.9 is no longer supported as of v0.11.0. Ensure your Python environment meets the `pykalman` requirements (>=3.10, <3.15).fixUpgrade your Python interpreter to version 3.10 or higher. Use a virtual environment to manage dependencies: `python3.10 -m venv .venv && source .venv/bin/activate`
affects: >=0.10.0, >=0.11.0
gotchaOlder versions of `pykalman` (prior to v0.10.0 and v0.11.1) may experience compatibility issues with `numpy` 2.x due to significant API changes in NumPy. This can lead to unexpected errors or incorrect behavior.fixUpgrade `pykalman` to the latest version (0.11.1 or higher) to ensure full compatibility with `numpy` 2.x. If upgrading `pykalman` is not an option, you may need to pin `numpy` to a `1.x` version (e.g., `numpy<2`).
affects: <0.10.0, <0.11.1
gotchaWhen using `KalmanFilter.em()` with `n_timesteps=1`, versions prior to v0.11.2 may encounter a crash. This specific edge case was resolved in a recent bugfix.fixUpgrade `pykalman` to version 0.11.2 or higher. If unable to upgrade, ensure `n_timesteps` is greater than 1 when using `em()`.
affects: <0.11.2
gotchaA bug existed in versions prior to v0.10.2 where time-varying transition covariance could be incorrectly overwritten by the initial matrix in the standard Kalman filter.fixUpgrade `pykalman` to version 0.10.2 or higher to resolve this issue. If using an older version, manually ensure that time-varying transition covariance is correctly handled or explicitly set if it's not meant to vary.
affects: <0.10.2
Errors
Common errors & fixes
TypeError: 'numpy.ndarray' object is not callable
This error often occurs when an older version of `pykalman` (e.g., <0.10.0 or <0.11.1) is used with `numpy` 2.x, due to breaking API changes in NumPy.
fixUpdate `pykalman` to the latest version (`pip install --upgrade pykalman`). If you cannot upgrade `pykalman`, downgrade `numpy` to a 1.x version (e.g., `pip install 'numpy<2'`).
AttributeError: 'KalmanFilter' object has no attribute 'filter'
This usually means you're trying to call a method like `filter()` or `smooth()` on an incorrectly initialized `KalmanFilter` object, or perhaps from an outdated fork, or you made a typo.
fixEnsure you are using `from pykalman import KalmanFilter` and that your `KalmanFilter` instance (`kf`) is properly created before calling its methods. Check the official documentation for correct method names and parameters.
ValueError: operands could not be broadcast together with shapes (X) (Y)
This error indicates a mismatch in the dimensions of the matrices provided to the KalmanFilter constructor (e.g., `transition_matrices`, `observation_matrices`, `covariance` matrices).
fixCarefully check the shapes of your input matrices. Ensure `transition_matrices` is (n_dim_state, n_dim_state), `observation_matrices` is (n_dim_obs, n_dim_state), and covariance matrices are symmetric with appropriate dimensions (e.g., `transition_covariance` is (n_dim_state, n_dim_state), `observation_covariance` is (n_dim_obs, n_dim_obs)).
Upgrade
Version history
0.11.2latest on PyPI · released Jan 31, 2026
Audit
Dependencies
numpyrequiredCore dependency for numerical operations, array manipulation, and mathematical functions.