A fast and extensible diagnostic CLI for Python-based Azure Functions projects. Supports both Programming Model v1 (function.json-based) and Programming Model v2 (decorator-based) projects.
- Getting random 500 errors and suspect misconfiguration?
- Need to verify your dev environment before CI/CD deployment?
- Want a quick health check without digging through docs?
Azure Functions Doctor helps save time by automating common environment diagnostics.
- Multi-Model Support: Works with both v1 (function.json) and v2 (decorator) projects
- Automatic Detection: Automatically detects your project's programming model
- Model-Specific Checks: Different requirements for v1 vs v2 (Python version, packages, etc.)
- Rich Diagnostics: Python version, venv, required packages, project files
- Extensible Rules: Customizable rules system for both programming models
- Rich Console Output: Clear formatting with hints and suggestions
- CI/CD Ready: JSON output for automated environments
Azure Functions Doctor uses a modular, rule-based architecture for extensibility and maintainability:
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ CLI Interface │ │ Core Diagnostic │ │ Rule System │
│ (cli.py) │───▶│ Engine │───▶│ (assets/rules/v2.json or v1.json) │
│ │ │ (doctor.py) │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
│ ▼ ▼
│ ┌──────────────────┐ ┌─────────────────┐
│ │ Handler │ │ Target/Version │
│ │ Dispatcher │ │ Resolver │
│ │ (handlers.py) │ │ (target_resolver │
│ └──────────────────┘ │ .py) │
│ │ └─────────────────┘
│ ▼
│ ┌──────────────────┐
│ │ Individual │
│ │ Handlers │
│ │ • file_exists │
│ │ • compare_version│
│ │ • check_package │
│ │ • validate_json │
│ └──────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌──────────────────┐
│ Output Formatter│ │ Results │
│ JSON / CLI │◀───│ Aggregator │
│ │ │ │
└─────────────────┘ └──────────────────┘
- CLI Interface: Entry point handling commands, flags, and output formatting
- Diagnostic Engine: Core orchestration logic loading rules and coordinating execution
- Rule System: Declarative JSON-based rule definitions for extensibility
- Handler Dispatcher: Routes rule types to appropriate handler functions
- Individual Handlers: Specific diagnostic implementations (file checks, version validation, etc.)
- Results Aggregator: Collects and structures all diagnostic outcomes
- Output Formatter: Renders results as colorized CLI output or machine-readable JSON
This design allows easy extension by adding new rules to src/azure_functions_doctor/assets/rules/v2.json (and v1.json for v1 projects) and implementing corresponding handlers, without modifying core engine logic.
- Python 3.9+
- Git
- (Optional) Azure Functions Core Tools v4+ (
npm i -g azure-functions-core-tools@4) - (Recommended) Unix-like shell or PowerShell for Makefile support
From PyPI:
pip install azure-functions-doctorOr from source:
git clone https://github.com/yeongseon/azure-functions-doctor-for-python.git
cd azure-functions-doctor-for-python
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e .azure-functions doctor
azure-functions --helpSample: examples/v2/http-trigger/diagnose-output.md
| Exit Code | Meaning |
|---|---|
| 0 | No fails (passes and warnings ok) |
| 1 | One or more fails detected |
| >1 | Reserved for internal errors |
Warnings (warn) do not fail the build. However, if there is at least one fail item the process exits with code 1 so CI can detect it immediately.
See examples/v2/http-trigger for:
- Minimal Azure Functions structure setup
- Running the CLI and inspecting results
See examples/v1/http-trigger for the legacy function.json model counterpart.
See examples/v1/multi-trigger for multiple v1 triggers (HTTP, Timer, Queue).
- Getting Started: docs/index.md
- Custom Rules: docs/rules.md
- Developer Guide: docs/development.md
We welcome issues and PRs!
Please see CONTRIBUTING.md for contribution guidelines.
If you find this useful, please star the repo!
This project is licensed under the MIT License.