Installing extension fails if the env var `PIP_REQUIRE_VIRTUALENV=true` is set

[frazar]

Describe the bug

The env var PIP_REQUIRE_VIRTUALENV=true is read by pip to prevent unintentional installation of Python packages outside of an activated virtualenv (see also the official pip docs). Some consider it a best practice to their it in your .bash_profile or .bashrc file.

Unfortunately, it seems that, when the PIP_REQUIRE_VIRTUALENV=true env var is set, the az CLI fails to install extensions.

# Ensure the extension is not installed
az extension remove --name azure-devops
# Set the env var and attempt to install the extension
export PIP_REQUIRE_VIRTUALENV=true 
# Try to install an extension
az extension add --name azure-devops

If I manually unset the env var before running az, the issue can be worked around:

unset PIP_REQUIRE_VIRTUALENV
az extension add --name azure-devops

Related command

az extension remove --name azure-devops
export PIP_REQUIRE_VIRTUALENV=true 
az extension add --name azure-devops

Errors

An error occurred. Pip failed with status code 3. Use --debug for more information.

Issue script & Debug output

DEBUG: cli.knack.cli: Command arguments: ['extension', 'add', '--name', 'azure-devops', '--debug']
DEBUG: cli.knack.cli: __init__ debug log:
Cannot enable color.
DEBUG: cli.knack.cli: Event: Cli.PreExecute []
DEBUG: cli.knack.cli: Event: CommandParser.OnGlobalArgumentsCreate [<function CLILogging.on_global_arguments at 0x7bb0925327a0>, <function OutputProducer.on_global_arguments at 0x7bb092276660>, <function CLIQuery.on_global_arguments at 0x7bb0922ac7c0>]
DEBUG: cli.knack.cli: Event: CommandInvoker.OnPreCommandTableCreate []
DEBUG: cli.azure.cli.core: Command index version or cloud profile is invalid or doesn't match the current command.
DEBUG: cli.azure.cli.core: Command index has been invalidated.
DEBUG: cli.azure.cli.core: No module found from index for '['extension', 'add', '--name', 'azure-devops', '--debug']'
DEBUG: cli.azure.cli.core: Loading all modules and extensions
DEBUG: cli.azure.cli.core: Discovered command modules: ['acr', 'acs', 'advisor', 'ams', 'apim', 'appconfig', 'appservice', 'aro', 'backup', 'batch', 'batchai', 'billing', 'botservice', 'cdn', 'cloud', 'cognitiveservices', 'compute_recommender', 'computefleet', 'config', 'configure', 'consumption', 'container', 'containerapp', 'cosmosdb', 'databoxedge', 'dls', 'dms', 'eventgrid', 'eventhubs', 'extension', 'feedback', 'find', 'hdinsight', 'identity', 'interactive', 'iot', 'keyvault', 'lab', 'managedservices', 'maps', 'marketplaceordering', 'monitor', 'mysql', 'netappfiles', 'network', 'policyinsights', 'postgresql', 'privatedns', 'profile', 'rdbms', 'redis', 'relay', 'resource', 'role', 'search', 'security', 'servicebus', 'serviceconnector', 'servicefabric', 'signalr', 'sql', 'sqlvm', 'storage', 'synapse', 'util', 'vm']
DEBUG: cli.azure.cli.core: Loading command modules...
DEBUG: cli.azure.cli.core: Loaded command modules in parallel:
DEBUG: cli.azure.cli.core: Name                  Load Time    Groups  Commands
DEBUG: cli.azure.cli.core: advisor                   0.010         3         6
DEBUG: cli.azure.cli.core: ams                       0.013        22       100
DEBUG: cli.azure.cli.core: appconfig                 0.010         9        47
DEBUG: cli.azure.cli.core: apim                      0.025        14        69
DEBUG: cli.azure.cli.core: acr                       0.155        36       149
DEBUG: cli.azure.cli.core: aro                       0.124         1        10
DEBUG: cli.azure.cli.core: backup                    0.014        17        65
DEBUG: cli.azure.cli.core: batchai                   0.006        10        30
DEBUG: cli.azure.cli.core: batch                     0.079        32        96
DEBUG: cli.azure.cli.core: botservice                0.007        12        42
DEBUG: cli.azure.cli.core: appservice                0.230        88       299
DEBUG: cli.azure.cli.core: cloud                     0.007         1         7
DEBUG: cli.azure.cli.core: billing                   0.092        19        52
DEBUG: cli.azure.cli.core: cognitiveservices         0.010        15        59
DEBUG: cli.azure.cli.core: compute_recommender       0.027         1         1
DEBUG: cli.azure.cli.core: computefleet              0.025         1         1
DEBUG: cli.azure.cli.core: config                    0.005         2         7
DEBUG: cli.azure.cli.core: configure                 0.005         2         5
DEBUG: cli.azure.cli.core: container                 0.036         2        17
DEBUG: cli.azure.cli.core: acs                       0.358        18        96
DEBUG: cli.azure.cli.core: consumption               0.061         8         9
DEBUG: cli.azure.cli.core: cosmosdb                  0.030        61       213
DEBUG: cli.azure.cli.core: databoxedge               0.033         2         2
DEBUG: cli.azure.cli.core: dls                       0.009         6        36
DEBUG: cli.azure.cli.core: dms                       0.006         3        22
DEBUG: cli.azure.cli.core: eventgrid                 0.006        25        96
DEBUG: cli.azure.cli.core: extension                 0.005         1         7
DEBUG: cli.azure.cli.core: feedback                  0.004         1         2
DEBUG: cli.azure.cli.core: find                      0.003         1         1
DEBUG: cli.azure.cli.core: hdinsight                 0.040        10        45
DEBUG: cli.azure.cli.core: eventhubs                 0.074        13        20
DEBUG: cli.azure.cli.core: interactive               0.001         1         1
DEBUG: cli.azure.cli.core: identity                  0.037         2         8
DEBUG: cli.azure.cli.core: keyvault                  0.016        20       114
DEBUG: cli.azure.cli.core: lab                       0.136         9        30
DEBUG: cli.azure.cli.core: iot                       0.200        18        81
DEBUG: cli.azure.cli.core: maps                      0.005         4         8
DEBUG: cli.azure.cli.core: containerapp              0.353        39       132
DEBUG: cli.azure.cli.core: managedservices           0.050         3         8
DEBUG: cli.azure.cli.core: marketplaceordering       0.016         1         2
DEBUG: cli.azure.cli.core: cdn                       0.492         8        50
DEBUG: cli.azure.cli.core: netappfiles               0.156         8        15
DEBUG: cli.azure.cli.core: mysql                     0.171        16        57
DEBUG: cli.azure.cli.core: policyinsights            0.067         9        17
DEBUG: cli.azure.cli.core: postgresql                0.101        20        88
DEBUG: cli.azure.cli.core: profile                   0.007         2         8
DEBUG: cli.azure.cli.core: privatedns                0.060        14        60
DEBUG: cli.azure.cli.core: redis                     0.005         7        38
DEBUG: cli.azure.cli.core: relay                     0.067         7         8
DEBUG: cli.azure.cli.core: rdbms                     0.086        22        90
DEBUG: cli.azure.cli.core: role                      0.004        17        62
DEBUG: cli.azure.cli.core: search                    0.025         7        20
DEBUG: cli.azure.cli.core: security                  0.020        47        98
DEBUG: cli.azure.cli.core: resource                  0.077        52       234
DEBUG: cli.azure.cli.core: servicebus                0.026        14        17
DEBUG: cli.azure.cli.core: serviceconnector          0.029        20       331
DEBUG: cli.azure.cli.core: signalr                   0.004        10        42
DEBUG: cli.azure.cli.core: servicefabric             0.039        27        80
DEBUG: cli.azure.cli.core: sql                       0.025        57       222
DEBUG: cli.azure.cli.core: storage                   0.061        61       278
DEBUG: cli.azure.cli.core: sqlvm                     0.079         4        20
DEBUG: cli.azure.cli.core: util                      0.003         3         7
DEBUG: cli.azure.cli.core: synapse                   0.017        54       246
DEBUG: cli.azure.cli.core: vm                        0.160        60       207
DEBUG: cli.azure.cli.core: monitor                   0.816        17        63
DEBUG: cli.azure.cli.core: network                   0.801       107       352
DEBUG: cli.azure.cli.core: Total (66)                1.542      1203      4705
DEBUG: cli.azure.cli.core: Loaded 1189 groups, 4705 commands.
DEBUG: cli.azure.cli.core: Updated command index in 0.003 seconds.
DEBUG: cli.azure.cli.core: Cached top-level help with 91 groups and 10 commands
DEBUG: cli.knack.cli: Event: CommandInvoker.OnPreCommandTableTruncate [<function AzCliLogging.init_command_file_logging at 0x7bb09143b380>]
DEBUG: cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/frazar/.azure/commands/2026-03-05.17-15-42.extension_add.2673.log'.
INFO: az_command_data_logger: command args: extension add --name {} --debug
DEBUG: cli.knack.cli: Event: CommandInvoker.OnPreArgumentLoad [<function register_global_subscription_argument.<locals>.add_subscription_parameter at 0x7bb091488e00>]
DEBUG: cli.knack.cli: Event: CommandInvoker.OnPostArgumentLoad []
DEBUG: cli.knack.cli: Event: CommandInvoker.OnPostCommandTableCreate [<function register_ids_argument.<locals>.add_ids_arguments at 0x7bb09148b100>, <function register_cache_arguments.<locals>.add_cache_arguments at 0x7bb09148b2e0>, <function register_upcoming_breaking_change_info.<locals>.update_breaking_change_info at 0x7bb09148b380>]
DEBUG: cli.knack.cli: Event: CommandInvoker.OnCommandTableLoaded []
DEBUG: cli.knack.cli: Event: CommandInvoker.OnPreParseArgs [<function _documentdb_deprecate at 0x7bb089ef6b60>]
DEBUG: cli.knack.cli: Event: CommandInvoker.OnPostParseArgs [<function OutputProducer.handle_output_argument at 0x7bb092276700>, <function CLIQuery.handle_query_parameter at 0x7bb0922ac860>, <function register_ids_argument.<locals>.parse_ids_arguments at 0x7bb09148b1a0>]
DEBUG: urllib3.connectionpool: Starting new HTTPS connection (1): aka.ms:443
DEBUG: urllib3.connectionpool: https://aka.ms:443 "GET /azure-cli-extension-index-v1 HTTP/1.1" 301 0
DEBUG: urllib3.connectionpool: Starting new HTTPS connection (1): azcliextensionsync.blob.core.windows.net:443
DEBUG: urllib3.connectionpool: https://azcliextensionsync.blob.core.windows.net:443 "GET /index1/index.json HTTP/1.1" 200 4585303
INFO: cli.azure.cli.core.extension._resolve: No preview versions need to be tried.
DEBUG: cli.azure.cli.core.extension._resolve: Candidates ['azure_devops-0.12.0-py2.py3-none-any.whl', 'azure_devops-0.17.0-py2.py3-none-any.whl', 'azure_devops-0.21.0-py2.py3-none-any.whl', 'azure_devops-0.26.0-py2.py3-none-any.whl', 'azure_devops-1.0.0-py2.py3-none-any.whl', 'azure_devops-1.0.1-py2.py3-none-any.whl', 'azure_devops-1.0.2-py2.py3-none-any.whl']
DEBUG: cli.azure.cli.core.extension._resolve: Candidates ['azure_devops-0.12.0-py2.py3-none-any.whl', 'azure_devops-0.17.0-py2.py3-none-any.whl', 'azure_devops-0.21.0-py2.py3-none-any.whl', 'azure_devops-0.26.0-py2.py3-none-any.whl', 'azure_devops-1.0.0-py2.py3-none-any.whl', 'azure_devops-1.0.1-py2.py3-none-any.whl', 'azure_devops-1.0.2-py2.py3-none-any.whl']
DEBUG: cli.azure.cli.core.extension._resolve: Candidates ['azure_devops-0.12.0-py2.py3-none-any.whl', 'azure_devops-0.17.0-py2.py3-none-any.whl', 'azure_devops-0.21.0-py2.py3-none-any.whl', 'azure_devops-0.26.0-py2.py3-none-any.whl', 'azure_devops-1.0.0-py2.py3-none-any.whl', 'azure_devops-1.0.1-py2.py3-none-any.whl', 'azure_devops-1.0.2-py2.py3-none-any.whl']
DEBUG: cli.azure.cli.core.extension._resolve: Candidates ['azure_devops-0.12.0-py2.py3-none-any.whl', 'azure_devops-0.17.0-py2.py3-none-any.whl', 'azure_devops-0.21.0-py2.py3-none-any.whl', 'azure_devops-0.26.0-py2.py3-none-any.whl', 'azure_devops-1.0.0-py2.py3-none-any.whl', 'azure_devops-1.0.1-py2.py3-none-any.whl', 'azure_devops-1.0.2-py2.py3-none-any.whl']
DEBUG: cli.azure.cli.core.extension._resolve: Candidates ['azure_devops-0.12.0-py2.py3-none-any.whl', 'azure_devops-0.17.0-py2.py3-none-any.whl', 'azure_devops-0.21.0-py2.py3-none-any.whl', 'azure_devops-0.26.0-py2.py3-none-any.whl', 'azure_devops-1.0.0-py2.py3-none-any.whl', 'azure_devops-1.0.1-py2.py3-none-any.whl', 'azure_devops-1.0.2-py2.py3-none-any.whl']
DEBUG: cli.azure.cli.core.extension._resolve: Chosen {'downloadUrl': 'https://azcliprod.blob.core.windows.net/cli-extensions/azure_devops-1.0.2-py2.py3-none-any.whl', 'filename': 'azure_devops-1.0.2-py2.py3-none-any.whl', 'metadata': {'azext.minCliCoreVersion': '2.30.0', 'classifiers': ['Development Status :: 4 - Beta', 'Intended Audience :: Developers', 'Intended Audience :: System Administrators', 'Programming Language :: Python', 'Programming Language :: Python :: 3', 'Programming Language :: Python :: 3.4', 'Programming Language :: Python :: 3.5', 'Programming Language :: Python :: 3.6', 'License :: OSI Approved :: MIT License'], 'extensions': {'python.details': {'contacts': [{'email': 'VSTS_Social@microsoft.com', 'name': 'Microsoft', 'role': 'author'}], 'document_names': {'description': 'DESCRIPTION.rst'}, 'project_urls': {'Home': 'https://github.com/Microsoft/azure-devops-cli-extension'}}}, 'extras': [], 'generator': 'bdist_wheel (0.30.0)', 'license': 'MIT', 'metadata_version': '2.0', 'name': 'azure-devops', 'run_requires': [{'requires': ['distro (>=1.6.0)']}], 'summary': 'Tools for managing Azure DevOps.', 'version': '1.0.2'}, 'sha256Digest': 'e2b0de02a3a745128c3f6e8c2711b8bbdbc1ba8b3afd2408a1581f35b069ba59'}
DEBUG: cli.azure.cli.core.extension.operations: Extension source is url? True
DEBUG: cli.azure.cli.core.extension.operations: Downloading https://azcliprod.blob.core.windows.net/cli-extensions/azure_devops-1.0.2-py2.py3-none-any.whl to /tmp/tmpjdbyyspm/azure_devops-1.0.2-py2.py3-none-any.whl
DEBUG: urllib3.connectionpool: Starting new HTTPS connection (1): azcliprod.blob.core.windows.net:443
DEBUG: urllib3.connectionpool: https://azcliprod.blob.core.windows.net:443 "GET /cli-extensions/azure_devops-1.0.2-py2.py3-none-any.whl HTTP/1.1" 200 1198093
DEBUG: cli.azure.cli.core.extension.operations: Downloaded to /tmp/tmpjdbyyspm/azure_devops-1.0.2-py2.py3-none-any.whl
DEBUG: cli.azure.cli.core.extension.operations: Validating the extension /tmp/tmpjdbyyspm/azure_devops-1.0.2-py2.py3-none-any.whl
DEBUG: cli.azure.cli.core.extension.operations: Checksum of /tmp/tmpjdbyyspm/azure_devops-1.0.2-py2.py3-none-any.whl is OK
DEBUG: cli.azure.cli.core.extension.operations: Validation successful on /tmp/tmpjdbyyspm/azure_devops-1.0.2-py2.py3-none-any.whl
DEBUG: cli.azure.cli.core.extension.operations: Linux distro check: Reading from: /etc/apt/sources.list.d/azure-cli.list
DEBUG: cli.azure.cli.core.extension.operations: Linux distro check: An error occurred while checking linux distribution version source list consistency.
DEBUG: cli.azure.cli.core.extension.operations: [Errno 2] No such file or directory: '/etc/apt/sources.list.d/azure-cli.list'
DEBUG: cli.azure.cli.core.extension.operations: Executing pip with args: ['install', '--target', '/home/frazar/.azure/cliextensions/azure-devops', '/tmp/tmpjdbyyspm/azure_devops-1.0.2-py2.py3-none-any.whl']
DEBUG: cli.azure.cli.core.extension.operations: Running: ['/opt/az/bin/python3', '-m', 'pip', 'install', '--target', '/home/frazar/.azure/cliextensions/azure-devops', '/tmp/tmpjdbyyspm/azure_devops-1.0.2-py2.py3-none-any.whl', '--disable-pip-version-check', '--no-cache-dir']
DEBUG: cli.azure.cli.core.extension.operations: ERROR: Could not find an activated virtualenv (required).

DEBUG: cli.azure.cli.core.extension.operations: Command '['/opt/az/bin/python3', '-m', 'pip', 'install', '--target', '/home/frazar/.azure/cliextensions/azure-devops', '/tmp/tmpjdbyyspm/azure_devops-1.0.2-py2.py3-none-any.whl', '--disable-pip-version-check', '--no-cache-dir']' returned non-zero exit status 3.
DEBUG: cli.azure.cli.core.extension.operations: Pip failed so deleting anything we might have installed at /home/frazar/.azure/cliextensions/azure-devops
DEBUG: cli.azure.cli.core.azclierror: Traceback (most recent call last):
  File "/opt/az/lib/python3.13/site-packages/knack/cli.py", line 233, in invoke
    cmd_result = self.invocation.execute(args)
  File "/opt/az/lib/python3.13/site-packages/azure/cli/core/commands/__init__.py", line 682, in execute
    raise ex
  File "/opt/az/lib/python3.13/site-packages/azure/cli/core/commands/__init__.py", line 812, in _run_jobs_serially
    results.append(self._run_job(expanded_arg, cmd_copy))
                   ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/az/lib/python3.13/site-packages/azure/cli/core/commands/__init__.py", line 781, in _run_job
    result = cmd_copy(params)
  File "/opt/az/lib/python3.13/site-packages/azure/cli/core/commands/__init__.py", line 336, in __call__
    return self.handler(*args, **kwargs)
           ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "/opt/az/lib/python3.13/site-packages/azure/cli/core/commands/command_operation.py", line 120, in handler
    return op(**command_args)
  File "/opt/az/lib/python3.13/site-packages/azure/cli/command_modules/extension/custom.py", line 16, in add_extension_cmd
    return add_extension(cli_ctx=cmd.cli_ctx, source=source, extension_name=extension_name, index_url=index_url,
                         yes=yes, pip_extra_index_urls=pip_extra_index_urls, pip_proxy=pip_proxy, system=system,
                         version=version, upgrade=upgrade, allow_preview=allow_preview)
  File "/opt/az/lib/python3.13/site-packages/azure/cli/core/extension/operations.py", line 343, in add_extension
    extension_name = _add_whl_ext(cli_ctx=cmd_cli_ctx, source=source, ext_sha256=ext_sha256,
                                  pip_extra_index_urls=pip_extra_index_urls, pip_proxy=pip_proxy, system=system)
  File "/opt/az/lib/python3.13/site-packages/azure/cli/core/extension/operations.py", line 172, in _add_whl_ext
    raise CLIError('An error occurred. Pip failed with status code {}. '
                   'Use --debug for more information.'.format(pip_status_code))
knack.util.CLIError: An error occurred. Pip failed with status code 3. Use --debug for more information.

ERROR: cli.azure.cli.core.azclierror: An error occurred. Pip failed with status code 3. Use --debug for more information.
ERROR: az_command_data_logger: An error occurred. Pip failed with status code 3. Use --debug for more information.
DEBUG: cli.knack.cli: Event: Cli.PostExecute [<function AzCliLogging.deinit_cmd_metadata_logging at 0x7bb09143b600>]
INFO: az_command_data_logger: exit code: 1
INFO: cli.__main__: Command ran in 7.580 seconds (init: 0.094, invoke: 7.486)
INFO: telemetry.main: Begin splitting cli events and extra events, total events: 1
INFO: telemetry.client: Accumulated 0 events. Flush the clients.
INFO: telemetry.main: Finish splitting cli events and extra events, cli events: 1
INFO: telemetry.save: Save telemetry record of length 4157 in cache file under /home/frazar/.azure/telemetry/20260305171547744
INFO: telemetry.main: Begin creating telemetry upload process.
INFO: telemetry.process: Creating upload process: "/opt/az/bin/python3 /opt/az/lib/python3.13/site-packages/azure/cli/telemetry/__init__.py /home/frazar/.azure /home/frazar/.azure/telemetry/20260305171547744"
INFO: telemetry.process: Return from creating process 2697
INFO: telemetry.main: Finish creating telemetry upload process.

Expected behavior

The extension is installed correctly regardless of the value of PIP_REQUIRE_VIRTUALENV.

Environment Summary

azure-cli 2.84.0

core 2.84.0
telemetry 1.1.0

Dependencies:
msal 1.35.0b1
azure-mgmt-resource 24.0.0

Python location '/opt/az/bin/python3'
Config directory '/home/frazar/.azure'
Extensions directory '/home/frazar/.azure/cliextensions'

Python (Linux) 3.13.11 (main, Feb 25 2026, 02:29:34) [GCC 13.3.0]

Legal docs and information: aka.ms/AzureCliLegal

Your CLI is up-to-date.

Additional context

Here is a Dockerfile to reproduce the issue in a portable way:

FROM ubuntu:24.04

RUN apt-get update && apt-get install curl -y

RUN curl -sL https://aka.ms/InstallAzureCLIDeb | bash

ENV PIP_REQUIRE_VIRTUALENV=true

RUN az extension add --name azure-devops --debug

Store the above in a file called Dockerfile then run docker build --progress=plain . in the same folder.

[dav-oss]

Out of curiosity:

ENV PIP_REQUIRE_VIRTUALENV=true 
RUN az extension add --name azure-devops --debug

do think the problem is here.
when pip is running is required to run in virtual enviroment which isn't activated at the time of running

[dav-oss]

I mean pip requires a virtual environment to run and "az ..... " runs at system wide level that's the conflict here.

[frazar]

Yes, I agree that az is doing nothing wrong. But as a user I was really surprised by the failure, it took me quite some time to realize what was happening. I did not even know that az internally uses pip to install extensions.

Perhaps az could somehow "mask" the variable before calling pip? Or override it via a pip CLI argument? Or even just warn the user that, with this env var, extensions can not be installed?

[microsoft-github-policy-service]

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @v-anvashist, @V-hmusukula.

[microsoft-github-policy-service]

🔔 Routing this issue to @act-platform-engineering-squad.

[microsoft-github-policy-service]

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @v-anvashist, @V-hmusukula, @act-platform-engineering-squad.

[a0x1ab]

Context for Copilot

Bug summary: az extension add fails when PIP_REQUIRE_VIRTUALENV=true is set in the environment, because that env var propagates to the pip subprocess used for extension installation, causing pip to exit with code 3 (requires virtualenv).

Root cause area: The extension installation logic calls pip as a subprocess. The fix is to strip (or override) PIP_REQUIRE_VIRTUALENV from the environment passed to pip, since the CLI manages its own isolated installation target directory and the restriction doesn't apply.

Key file to investigate:

• src/azure-cli-core/azure/cli/core/extension/operations.py — look for where pip is invoked (subprocess call). The subprocess env should explicitly unset PIP_REQUIRE_VIRTUALENV (and potentially other pip env-var restrictions like PIP_REQUIRE_HASHES) before calling pip.

Suggested fix pattern:

import os, subprocess
env = os.environ.copy()
env.pop("PIP_REQUIRE_VIRTUALENV", None)
subprocess.run([sys.executable, "-m", "pip", "install", ...], env=env, ...)

Acceptance criteria:

• az extension add --name azure-devops succeeds even when PIP_REQUIRE_VIRTUALENV=true is exported.
• Existing tests continue to pass.
• A unit test or note in the PR explaining the change is welcome.

---

Posted by agent-assist (autonomous bug-fix pipeline).