pyod

.. image:: https://raw.githubusercontent.com/yzhao062/pyod/master/brand/pyod-icon.svg :target: https://pyod.dev :alt: PyOD Ecosystem :width: 84px

Python Outlier Detection (PyOD) 3

PyOD 3: Agentic Anomaly Detection At Scale

|badge_website| |badge_pypi| |badge_anaconda| |badge_docs| |badge_stars| |badge_forks| |badge_downloads| |badge_testing| |badge_coverage| |badge_maintainability| |badge_license| |badge_benchmark|

.. |badge_website| image:: https://img.shields.io/badge/website-pyod.dev-990000 :target: https://pyod.dev :alt: Website

.. |badge_pypi| image:: https://img.shields.io/pypi/v/pyod.svg?color=brightgreen :target: https://pypi.org/project/pyod/ :alt: PyPI version

.. |badge_anaconda| image:: https://anaconda.org/conda-forge/pyod/badges/version.svg :target: https://anaconda.org/conda-forge/pyod :alt: Anaconda version

.. |badge_docs| image:: https://readthedocs.org/projects/pyod/badge/?version=latest :target: https://pyod.readthedocs.io/en/latest/?badge=latest :alt: Documentation status

.. |badge_stars| image:: https://img.shields.io/github/stars/yzhao062/pyod.svg :target: https://github.com/yzhao062/pyod/stargazers :alt: GitHub stars

.. |badge_forks| image:: https://img.shields.io/github/forks/yzhao062/pyod.svg?color=blue :target: https://github.com/yzhao062/pyod/network :alt: GitHub forks

.. |badge_downloads| image:: https://pepy.tech/badge/pyod :target: https://pepy.tech/project/pyod :alt: Downloads

.. |badge_testing| image:: https://github.com/yzhao062/pyod/actions/workflows/testing.yml/badge.svg :target: https://github.com/yzhao062/pyod/actions/workflows/testing.yml :alt: Testing

.. |badge_coverage| image:: https://coveralls.io/repos/github/yzhao062/pyod/badge.svg :target: https://coveralls.io/github/yzhao062/pyod :alt: Coverage Status

.. |badge_maintainability| image:: https://api.codeclimate.com/v1/badges/bdc3d8d0454274c753c4/maintainability :target: https://codeclimate.com/github/yzhao062/Pyod/maintainability :alt: Maintainability

.. |badge_license| image:: https://img.shields.io/github/license/yzhao062/pyod.svg :target: https://github.com/yzhao062/pyod/blob/master/LICENSE :alt: License

.. |badge_benchmark| image:: https://img.shields.io/badge/ADBench-benchmark_results-pink :target: https://github.com/Minqi824/ADBench :alt: Benchmark

---

**PyOD is agent-ready.** Claude Code and Codex can use the ``od-expert`` skill to drive ADEngine investigations, while MCP-compatible agents can query PyOD's detector knowledge and planning tools. The classic ``fit``/``predict`` API stays unchanged.

---

PyOD 3 is the most comprehensive Python library for anomaly detection. Four pillars:

=========================== ======================================================================================== Pillar What it means =========================== ======================================================================================== Multi-Modal 61 detectors across tabular, time series, graph, text, image, and audio data, one API Full Lifecycle From raw data to explained anomalies and next-step guidance in a single call Agentic od-expert turns natural-language requests into ADEngine workflows; MCP exposes structured tools for other agents Most Used 46+ million downloads; benchmark-backed routing (ADBench, TSB-AD, BOND, NLP-ADBench) =========================== ========================================================================================

Install ^^^^^^^

Core library (required for every activation path):

.. code-block:: bash

pip install pyod

Then pick the activation path that matches your agent stack:

.. code-block:: bash

# 1. Claude Code / Codex — enables the od-expert skill
pyod install skill              # Claude Code: user-global (~/.claude/skills/)
pyod install skill --project    # Codex: project-local (./skills/, Codex has no user-global dir)

# 2. Any MCP-compatible LLM — requires the optional mcp extra
pip install pyod[mcp]
pyod mcp serve                 # alias for `python -m pyod.mcp_server`

# 3. Pure Python — no extra step
#    from pyod.utils.ad_engine import ADEngine

Run pyod info at any time to see version, detector counts, and the install state of each activation path. pyod info also detects which agent stack you have installed (~/.claude/ for Claude Code, ~/.codex/ for Codex) and recommends the right install command.

For conda, source install, dependency details, and troubleshooting, see the full installation guide <https://pyod.readthedocs.io/en/latest/install.html>__. The legacy pyod-install-skill command from v3.0.0 still works as an alias for pyod install skill.

Outlier Detection with 5 Lines of Code (pip install pyod):

.. code-block:: python

from pyod.models.iforest import IForest
clf = IForest()
clf.fit(X_train)
y_train_scores = clf.decision_scores_          # training anomaly scores
y_test_scores = clf.decision_function(X_test)   # test anomaly scores

Three ways to use PyOD:

========= ===================== ====================================================================== ======================================= Layer Name When to use Entry point ========= ===================== ====================================================================== ======================================= 1 Classic API You know which detector you want Layer 1 examples <https://pyod.readthedocs.io/en/latest/examples/tabular.html>__ 2 ADEngine You want PyOD to choose, compare, and assess automatically Layer 2 walkthrough <https://pyod.readthedocs.io/en/latest/examples/adengine.html>__ 3 Agentic Investigation You want an AI agent to drive OD through natural conversation Layer 3 walkthrough <https://pyod.readthedocs.io/en/latest/examples/agentic.html>__ ========= ===================== ====================================================================== =======================================

Layers 2 and 3 are powered by ADEngine, PyOD's lifecycle orchestration core. The full multi-turn Layer 3 investigation flow is available through the od-expert skill for Claude Code and Codex. The MCP server (python -m pyod.mcp_server) exposes ten stateless tools for MCP-compatible LLMs, spanning knowledge queries (list_detectors, explain_detector, compare_detectors, get_benchmarks), planning (profile_data, plan_detection, build_detector), and detection (run_detection, analyze_results, explain_findings); stateful investigate / iterate MCP tools are deferred.

.. image:: https://raw.githubusercontent.com/yzhao062/pyod/development/docs/figs/agentic-demo.png :alt: PyOD 3 agentic investigation demo on cardiotocography dataset :align: center :width: 720

The figure above shows a real 5-turn agentic conversation on the UCI Cardiotocography dataset. See the full walkthrough <https://pyod.readthedocs.io/en/latest/examples/agentic.html>, runnable agentic example <https://github.com/yzhao062/pyod/blob/development/examples/agentic_example.py>, or interactive HTML demo <https://htmlpreview.github.io/?https://github.com/yzhao062/pyod/blob/development/examples/agentic_demo.html>__.

PyOD Ecosystem & Resources: NLP-ADBench <https://github.com/USC-FORTIS/NLP-ADBench>__ (NLP anomaly detection) | TODS <https://github.com/datamllab/tods>__ (time-series) | PyGOD <https://pygod.org/>__ (graph) | ADBench <https://github.com/Minqi824/ADBench>__ (benchmark) | AD-LLM <https://arxiv.org/abs/2412.11142>__ (LLM-based AD) [#Yang2024ad]_ | Resources <https://github.com/yzhao062/anomaly-detection-resources>__

---

About PyOD ^^^^^^^^^^

PyOD, established in 2017, is the longest-running and most widely used Python library for anomaly detection. With 46+ million downloads <https://pepy.tech/project/pyod>, it serves both academic research (featured in Analytics Vidhya <https://www.analyticsvidhya.com/blog/2019/02/outlier-detection-python-pyod/>, KDnuggets <https://www.kdnuggets.com/2019/02/outlier-detection-methods-cheat-sheet.html>, and Towards Data Science <https://towardsdatascience.com/anomaly-detection-for-dummies-15f148e559c1>) and commercial products.

V3 extends the library with ADEngine (lifecycle orchestration) and the od-expert skill (agentic workflow), while keeping the classic fit/predict API fully backward-compatible. V3 is built on SUOD [#Zhao2021SUOD]_ for fast parallel training and numba JIT for per-model speedups.

Impact & Recognition:

=================================== =========================================================================== Area Examples =================================== =========================================================================== Space & science European Space Agency OPS-SAT spacecraft telemetry benchmark <https://www.nature.com/articles/s41597-025-05035-3>__ (Nature Scientific Data, 2025) uses PyOD for all 30 algorithms. Enterprise deployment Walmart (1M+ daily pricing updates, KDD 2019), Databricks (Kakapo framework integrating PyOD with MLflow/Hyperopt; insider-threat detection solution), IQVIA (123K+ pharmacy claims), Altair AI Studio, Ericsson (patent WO2023166515A1 <https://patents.google.com/patent/WO2023166515A1>). Books Outlier Detection in Python <https://www.manning.com/books/outlier-detection-in-python> (Brett Kennedy, Manning); Handbook of Anomaly Detection with Python (Chris Kuo, Columbia); Finding Ghosts in Your Data <https://link.springer.com/book/10.1007/978-1-4842-8870-2>__ (Kevin Feasel, Apress). Courses DataCamp Anomaly Detection in Python <https://www.datacamp.com/courses/anomaly-detection-in-python>__ (19M+ platform learners), Manning liveProject <https://www.manning.com/liveproject/using-pyod-and-ensembles-methods>, O'Reilly video edition, multiple Udemy courses. Podcasts Talk Python To Me #497 <https://talkpython.fm/episodes/show/497/outlier-detection-with-python>, Real Python Podcast #208 <https://realpython.com/podcasts/rpp/208/>. International Tutorials in 5 non-English languages: Chinese (CSDN, Zhihu, 搜狐, 机器之心, aidoczh.com <https://www.aidoczh.com> full doc translation), Japanese, Korean, German, Spanish. =================================== ===========================================================================

See the full impact page <https://pyod.readthedocs.io/en/latest/impact.html>__ on Read the Docs for the complete list of citations, enterprise deployments, patents, and media coverage.

Citing PyOD:

If you use PyOD in a scientific publication, we would appreciate citations to the following paper(s):

PyOD 2: A Python Library for Outlier Detection with LLM-powered Model Selection <https://arxiv.org/abs/2412.12154>__ is available as a preprint. If you use PyOD in a scientific publication, we would appreciate citations to the following paper::

@inproceedings{chen2025pyod,
  title={Pyod 2: A python library for outlier detection with llm-powered model selection},
  author={Chen, Sihan and Qian, Zhuangzhuang and Siu, Wingchun and Hu, Xingcan and Li, Jiaqi and Li, Shawn and Qin, Yuehan and Yang, Tiankai and Xiao, Zhuo and Ye, Wanghao and others},
  booktitle={Companion Proceedings of the ACM on Web Conference 2025},
  pages={2807--2810},
  year={2025}
}

`PyOD paper <http