azure-functions-doctor 0.16.2

Diagnostic tool for Azure Functions Python v2 programming model

Azure Functions Doctor

Read this in: 한국어 | 日本語 | 简体中文

Azure Functions Doctor is the pre-deploy health gate for Azure Functions Python v2 projects — a diagnostic CLI that catches configuration issues, missing dependencies, and environment problems before they cause runtime failures in production.

---

Part of the Azure Functions Python DX Toolkit → Bring FastAPI-like developer experience to Azure Functions

Why this exists

Deploying a broken Azure Functions app is expensive — the worker starts, the host reads config, and only then does it surface the issue in a production log. Common problems that slip through:

• Missing dependencies — azure-functions not in requirements.txt, discovered only at cold start
• Invalid configuration — host.json misconfigured, extensionBundle missing or outdated
• Runtime incompatibilities — Python version mismatch with Azure Functions runtime
• Silent failures — no virtual environment, Core Tools not installed, Application Insights key missing

azure-functions-doctor moves that failure left — catch it locally or in CI, not in production.

What it does

• 14+ diagnostic checks — Python version, dependencies, host.json, Core Tools, Durable Functions, and more
• Multiple output formats — table, JSON, SARIF, JUnit for CI integration
• Profile support — minimal or full rulesets depending on your needs
• Official GitHub Action — yeongseon/azure-functions-doctor@v1 for CI gates

Scope

This repository targets the decorator-based Azure Functions Python v2 programming model only.

• Supported model: func.FunctionApp() with decorators such as @app.route()
• Unsupported model: legacy function.json-based Python v1 projects

Use azure-functions-doctor as part of a pre-deployment checklist alongside azure-functions-logging for observability.

Installation

From PyPI:

pip install azure-functions-doctor

From source:

git clone https://github.com/yeongseon/azure-functions-doctor.git
cd azure-functions-doctor
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Quick Start

Run the doctor in the current project:

azure-functions doctor

Run against a specific project:

azure-functions doctor --path ./examples/v2/http-trigger

Use a required-only profile:

azure-functions doctor --profile minimal

Output JSON for CI:

azure-functions doctor --format json

CI Integration

Use azure-functions-doctor as a CI gate to block deployments on required failures.

GitHub Actions (CLI)

- name: Run azure-functions-doctor
  run: |
    pip install azure-functions-doctor
    azure-functions doctor --profile minimal --format json --output doctor.json

- name: Upload report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: doctor-report
    path: doctor.json

Official GitHub Action

- uses: yeongseon/azure-functions-doctor@v1
  with:
    path: .
    profile: minimal
    format: sarif
    output: doctor.sarif
    upload-sarif: "true"

See docs/examples/ci_integration.md for Azure DevOps, pre-commit, VS Code, and SARIF upload examples.

Demo

The demo below is generated from demo/doctor-demo.tape with VHS. It runs the real azure-functions doctor CLI against the representative example and then against an intentionally broken copy to show the pass/fail contrast.

The final terminal state is also captured as a static image for quick inspection.

Features

The default ruleset includes checks for:

• Azure Functions Python v2 decorator usage
• Python version
• virtual environment activation
• Python executable availability
• requirements.txt
• azure-functions dependency declaration
• host.json
• local.settings.json (optional)
• Azure Functions Core Tools presence and version (optional)
• Durable Functions host configuration (optional)
• Application Insights configuration (optional)
• extensionBundle configuration (optional)
• ASGI/WSGI callable exposure (optional)
• common unwanted files in the project tree (optional)

Examples

• examples/v2/http-trigger/README.md
• examples/v2/multi-trigger/README.md

Requirements

• Python 3.10+
• Hatch for development workflows
• Azure Functions Core Tools v4+ recommended for local runs

When to use

• Before deploying an Azure Functions app (local pre-flight check)
• In CI/CD pipelines as a deployment gate
• When onboarding a new developer to catch environment setup issues
• After upgrading Python version or Azure Functions runtime
• As a pre-commit hook for configuration validation

Documentation

• docs/index.md
• docs/usage.md
• docs/rules.md
• docs/diagnostics.md
• docs/development.md
• docs/examples/ci_integration.md

Ecosystem

Part of the Azure Functions Python DX Toolkit:

Package	Role
azure-functions-validation	Request and response validation
azure-functions-openapi	OpenAPI spec and Swagger UI
azure-functions-logging	Structured logging and observability
azure-functions-doctor	Pre-deploy diagnostic CLI
azure-functions-scaffold	Project scaffolding
azure-functions-python-cookbook	Recipes and examples

Disclaimer

This project is an independent community project and is not affiliated with, endorsed by, or maintained by Microsoft.

Azure and Azure Functions are trademarks of Microsoft Corporation.

License

MIT