Microsoft Azure CLI Developer Tools

Common errors

• error: invalid command 'bdist_wheel' or similar build-related errors during installation.

  cause Often caused by outdated or conflicting `setuptools` versions, especially when `azdev` pins a specific version.
  fix Try explicitly installing a compatible `setuptools` version before `azdev`: `pip install 'setuptools==70.0.0' && pip install azdev` (check `azdev` release notes for exact `setuptools` pin).

• pip._vendor.packaging.version.InvalidVersion: Invalid version: '25.3'

  cause This error, particularly after a pip upgrade, indicates that `azdev` or one of its dependencies is incompatible with the new `pip` version due to internal changes (e.g., pip 25.3 removed support for legacy `setup.py develop` editable method).
  fix Pin `pip` to a compatible version as specified in `azdev`'s release notes (e.g., `pip install 'pip==25.2' && pip install azdev`).

• azdev: error: argument {command}: invalid choice: 'my-non-existent-module'

  cause The `azdev` command (e.g., `linter`, `test`) was invoked with a module or extension name that `azdev` cannot find in the configured Azure CLI or extension repositories.
  fix Verify that you have correctly set up your `azdev` environment using `azdev setup --cli <path> --repo <path>` and that the module/extension name you are passing exists within those repositories. Run `azdev --help` or `azdev <command> --help` to check valid options.

Warnings

• gotcha azdev is explicitly designed for internal use and local machine execution only. It must NOT be used to process input from untrusted sources or deployed behind any external-facing application due to potential security risks.
  Fix: Adhere strictly to its intended use case for local Azure CLI development and testing environments.
• breaking Specific versions of `pip` and `setuptools` have been pinned in `azdev` releases (e.g., pip to 25.2 in v0.2.8, setuptools to 70.0.0 in v0.2.4). This can lead to installation conflicts or `setup.py develop` issues with newer or older versions of these build tools.
  Fix: If encountering installation errors, ensure your `pip` and `setuptools` versions align with `azdev`'s requirements. You may need to downgrade or upgrade `pip` and `setuptools` specifically: `pip install 'pip==25.2' 'setuptools==70.0.0'` (adjust versions as per release notes).
• gotcha Python version compatibility for `azdev` requires Python >=3.9. While newer Python versions (up to 3.13) are tested and supported, older documentation might mention specific Python 3.x versions (e.g., 3.6-3.8) as recommended. Always verify the `requires_python` metadata for the installed version.
  Fix: Ensure you are running Python 3.9 or newer. If you experience unexpected behavior, cross-reference the `azdev` GitHub release notes and PyPI metadata for any specific Python version recommendations or known issues.

Install

• pip install azdev Install latest stable version

Quickstart

The `azdev` tool is primarily a command-line interface. This quickstart demonstrates how to install `azdev`, set up your local Azure CLI development environment by pointing to your cloned repositories, and run a basic linter check. Full development requires cloning the official Azure CLI and potentially `azure-cli-extensions` repositories.

# 1. Install azdev
pip install azdev

# 2. Fork and clone the Azure CLI and/or Azure CLI Extensions repositories
# For example, to a folder like '~/azure-cli' and '~/azure-cli-extensions'

# 3. Set up your development environment interactively
azdev setup --cli ~/azure-cli --repo ~/azure-cli-extensions

# 4. Run a basic linter check on a module (replace 'my-module' with an actual module or extension name)
# cd ~/azure-cli
azdev linter my-module