Azure Functions Doctor

Validate Azure Functions Python v2 projects before they fail in local runtime or CI.

azure-functions-doctor is a diagnostics CLI and API that checks required project health signals, reports optional operational guidance, and returns deterministic exit codes for automation.

Why teams use it

• Catch missing baseline files (host.json, requirements.txt) early
• Verify runtime and dependency declarations before deployment
• Gate merges on required blockers while preserving optional guidance
• Export machine-readable diagnostics for CI and code-scanning systems

Working example

Install and run in the current project:

python -m pip install azure-functions-doctor
azure-functions doctor

Run required-only checks in CI:

azure-functions doctor --profile minimal --format json --output doctor.json

What it checks

Built-in diagnostics currently include:

• Python version support
• v2 decorator programming model signal
• virtual environment presence
• Python executable path validity
• requirements.txt and azure-functions declaration
• host.json presence
• optional tooling, telemetry, extension, and cleanup checks

Reference: Rule Inventory

Output and gating model

Item statuses:

• pass
• warn (optional check failed)
• fail (required check failed)

Exit code contract:

• 0 when required checks all pass
• 1 when any required check fails

This enables direct CI usage without custom gate wrappers.

Feature highlights

• Declarative rules with schema validation
• Profile-based execution (full, minimal)
• Multiple output formats (table, json, sarif, junit)
• Custom rule file support via --rules
• Programmatic API for pipeline/tool integration

CLI and API entry points

• CLI: azure-functions doctor
• API: from azure_functions_doctor.api import run_diagnostics

Programmatic example:

from azure_functions_doctor.api import run_diagnostics


def has_required_failures(path: str) -> bool:
    for section in run_diagnostics(path=path, profile="minimal", rules_path=None):
        for item in section["items"]:
            if item["status"] == "fail":
                return True
    return False

Documentation map

Get started

• Installation
• Quickstart
• Configuration

User guide

• CLI Usage
• Diagnostics
• Rules
• Rule Inventory
• Minimal Profile
• JSON Output Contract
• Handlers

Examples

• Basic Check
• CI Integration
• Custom Rules

Maintenance and policies

• Supported Versions
• Semver Policy
• Troubleshooting
• FAQ

Typical adoption path

1. Install package in your development environment
2. Run azure-functions doctor locally and fix required failures
3. Add CI job using --profile minimal --format json
4. Publish JSON/SARIF/JUnit artifacts for visibility
5. Add optional custom rules for organization-specific policy

Notes on scope

Note

Azure Functions Doctor targets the Python v2 decorator model. Legacy Python v1 (function.json-oriented) projects are out of scope.

Need help?

Start with Troubleshooting, then review FAQ. If behavior looks incorrect, include command, version, and JSON output snippet when opening an issue.