{"id":8131,"library":"dtaidistance","title":"DTAIDistance: Dynamic Time Warping for Time Series","description":"DTAIDistance is a Python library providing highly optimized distance measures for time series, primarily focusing on Dynamic Time Warping (DTW). It features both a pure Python implementation and a significantly faster C implementation, making it suitable for performance-critical applications. The library also includes functionalities for time series clustering, multi-dimensional DTW, and subsequence search. It is actively maintained by the DTAI Research Group, with the current stable version being 2.4.0.","status":"active","version":"2.4.0","language":"en","source_language":"en","source_url":"https://github.com/wannesm/dtaidistance","tags":["time series","DTW","dynamic time warping","distance","clustering","signal processing","fast","C-extension","similarity"],"install":[{"cmd":"pip install dtaidistance","lang":"bash","label":"Standard pip installation"},{"cmd":"conda install -c conda-forge dtaidistance","lang":"bash","label":"Conda installation (pre-compiled binaries)"}],"dependencies":[{"reason":"Required for compiling the fast C implementations.","package":"cython","optional":false},{"reason":"Commonly used for input time series data; required for compiling Numpy-compatible C code, though optional for the core C library in v2.","package":"numpy","optional":false},{"reason":"For visualizing warping paths and other DTW-related plots.","package":"matplotlib","optional":true},{"reason":"For integration with existing clustering methods like scipy.cluster.hierarchy.linkage.","package":"scipy","optional":true},{"reason":"For displaying progress bars during long computations.","package":"tqdm","optional":true}],"imports":[{"symbol":"dtw","correct":"from dtaidistance import dtw"},{"note":"Commonly aliased as `dtwvis` for brevity.","symbol":"dtw_visualisation","correct":"from dtaidistance import dtw_visualisation as dtwvis"},{"symbol":"dtw_ndim","correct":"from dtaidistance import dtw_ndim"}],"quickstart":{"code":"import numpy as np\nfrom dtaidistance import dtw\n\n# Define two sample time series\ns1 = np.array([0.0, 0, 1, 2, 1, 0, 1, 0, 0])\ns2 = np.array([0.0, 1, 2, 0, 0, 0, 0, 0, 0])\n\n# Compute the DTW distance using the fast C implementation\ndistance = dtw.distance_fast(s1, s2)\nprint(f\"DTW distance: {distance:.2f}\")\n\n# Optionally, visualize the warping path (requires matplotlib)\ntry:\n    from dtaidistance import dtw_visualisation as dtwvis\n    path = dtw.warping_path(s1, s2)\n    dtwvis.plot_warping(s1, s2, path, filename=\"warping_path.png\")\n    print(\"Warping path visualized in warping_path.png\")\nexcept ImportError:\n    print(\"Matplotlib not installed, skipping visualization.\")\n","lang":"python","description":"This quickstart demonstrates how to calculate the Dynamic Time Warping (DTW) distance between two NumPy arrays using the `distance_fast` method for optimal performance. It also includes an optional step to visualize the warping path, which requires `matplotlib`."},"warnings":[{"fix":"Ensure NumPy is installed (`pip install numpy`) if you are passing NumPy arrays to DTAIDistance functions. If you encounter compilation issues without NumPy, ensure Cython is installed or use pre-compiled binaries via Conda.","message":"In version 2, NumPy became an optional dependency for compiling the C library. While the core C library can be compiled without it (requiring only Cython), most practical applications using NumPy arrays as input will still implicitly require NumPy.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Replace calls to `dtw.distance()` with `dtw.distance_fast()` and `dtw.distance_matrix()` with `dtw.distance_matrix_fast()`. Ensure the C library is correctly compiled and available (see 'Problems' section).","message":"The default `dtw.distance()` and `dtw.distance_matrix()` methods use a pure Python implementation, which is significantly slower than the C-based optimized versions. For optimal performance, always use `dtw.distance_fast()` and `dtw.distance_matrix_fast()`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"On Windows, ensure 'Build Tools for Visual Studio' (with C++ development workload) are installed. On Unix, ensure `gcc` and `OpenMP` development libraries are present. If OpenMP linking issues persist, try `pip install --global-option=--noopenmp dtaidistance` or refer to documentation for `--forcegnugcc`, `--forcellvm` options. Verify C library availability with `dtw.try_import_c(verbose=True)`.","message":"Installing on Windows or certain Unix systems (e.g., macOS) might fail to compile the fast C extensions or correctly link OpenMP, leading to the Python-only fallback or runtime errors when parallelization is expected. This can result in slower performance or the 'C library not available' error.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For extremely large datasets, consider strategies to reduce the matrix size (e.g., computing only a `block` of distances), using pruning options like `max_dist` or `window`, or exploring approximate DTW methods outside of `dtaidistance` if exact DTW is not feasible for your scale. Monitor memory usage carefully.","message":"Computing `distance_matrix_fast` for a very large number of long time series can lead to `MemoryError` due to the quadratic space complexity of storing the full distance matrix.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure your system has a C/C++ compiler (e.g., 'Build Tools for Visual Studio' on Windows, `gcc` on Linux/macOS) and OpenMP support. Reinstall using `pip install --no-cache-dir --force-reinstall dtaidistance`. If OpenMP issues persist, try `pip install --global-option=--noopenmp dtaidistance`. You can check the C library status with `from dtaidistance import dtw; dtw.try_import_c(verbose=True)`.","cause":"The C extensions for `dtaidistance` failed to compile during installation or could not be found/loaded at runtime. This often happens if a suitable C/C++ compiler or OpenMP libraries are missing on the system.","error":"Exception: The compiled dtaidistance C library is not available. See the documentation for alternative installation options."},{"fix":"Reduce the number of series or the length of individual series if possible. Use the `block` argument in `distance_matrix_fast` to compute only a subset of the matrix. Consider using pruning options like `max_dist` or `window` to reduce the computation cost per pair, although this doesn't reduce the matrix storage itself.","cause":"Attempting to compute a distance matrix (`dtw.distance_matrix_fast`) for a large number of time series, causing the resulting NxN matrix (where N is the number of series) to exceed available system memory. DTW itself has quadratic time complexity, but the matrix storage is the main memory culprit.","error":"MemoryError: Unable to allocate ... bytes"},{"fix":"This is often a symptom of the 'C library not available' problem. Follow the steps to ensure your C/C++ compiler and OpenMP setup are correct and reinstall the library. Using `dtw.distance_fast()` or `dtw.distance_matrix_fast()` explicitly will also trigger this warning if the C library is indeed missing.","cause":"The C extensions for `dtaidistance` were not successfully compiled or loaded, so the library is defaulting to its slower pure Python implementation.","error":"RuntimeWarning: C-library has not been compiled, falling back to Python implementation. This will be slower."}]}