Azure Pipelines：「Version spec ... did not match any version in Agent.ToolsDirectory」
Use Python version のタスク UsePythonVersion@0 は、python.org から Python を入れるわけではありません。エージェントのツール キャッシュ（Agent.ToolsDirectory のフォルダー）を探し、そのバージョンがなければ、GitHub Actions の python-versions のレジストリからビルドをキャッシュにダウンロードしようとします。キャッシュにもなく、ダウンロードもできなかったときに、このエラーが出ます。
失敗しているビルドがプルリクエストのビルド検証なら、プルリクエストはそれを待っています：JetBrains IDE のプラグイン Azure DevOps Pull Requests は、プルリクエストのブランチ ポリシーを状態つきで PyCharm や IntelliJ IDEA に並べ、Pro なら直しを push したあとに、失敗したビルド ポリシーをもう一度動かせます。JetBrains Marketplace で入れる
出るメッセージ
##[error]Version spec 3.x for architecture x64 did not match any version in Agent.ToolsDirectory.（指定したバージョンが Agent.ToolsDirectory のどれとも合わない、という意味）。そのあとにVersions inとフォルダーに続けてキャッシュにあるバージョンが並び、Microsoft がホストするエージェント向けとセルフホスト向けのヒントが1行ずつ出ます。- タスクがダウンロードを試みたなら、その前の行に失敗の理由が出ます：
Failed to download Python from the Github Actions python registry、Could not find Python matching spec ... in the python-versions registry、Failed to download Python versions manifest。
タスクがしていること
- タスクのソース（バージョン 0.283）では、まず
versionSpecとarchitectureに合う Python をキャッシュから探します。なく、disableDownloadFromRegistryが既定の false なら、actions/python-versions からダウンロードしてもう一度探します。両方だめなときだけ、このエラーで止まります。 - レジストリにあるのは、そのバージョン一覧（マニフェスト）に載っているシステム向けのビルドだけです。タスク自身が、プロキシ越しのダウンロードはできないと言っています。
githubTokenを渡さないと匿名のリクエストになり、GitHub の匿名ダウンロードの上限に当たることがあります。 - Microsoft のタスクのページには、セルフホストのエージェントではダウンロードできないとまだ書かれています。ただ、タスクのコードはどのエージェントでもダウンロードを試みるので、インターネットにつながり、対応するシステムのセルフホストのエージェントでも取れます。
Microsoft がホストするエージェント
- イメージにキャッシュされている Python はいくつかだけです。いまの
ubuntu-24.04とwindows-2022では 3.11・3.12・3.13・3.14・3.15（runner-images のリポジトリの readme）。それ以外のバージョンはダウンロードを通ります。 - パッチまでの指定ではなく、
'3.12'のようなマイナーまでで指定します。キャッシュのパッチはイメージの更新ごとに変わり、タスクも完全なバージョンの指定は勧めないと警告します。 - 匿名の上限でダウンロードが失敗するなら、トークンを渡します。GitHub の個人用アクセス トークンをシークレットの変数に入れ、
githubToken: $(GITHUB_TOKEN)とします。読むのは公開リポジトリだけです。 - Microsoft のタスクのページでは、ホストされた Windows のエージェントには x86 と x64 の両方があり、Linux と macOS にはないとされています。
architecture: 'x86'が通るのは Windows だけです。
- task: UsePythonVersion@0
inputs:
versionSpec: '3.12'
githubToken: $(GITHUB_TOKEN)セルフホストのエージェント
- Microsoft のタスクのページの並びで、Python を自分でツール キャッシュに置きます。
$AGENT_TOOLSDIRECTORY/Python/3.12.10/x64/に展開した Python を入れ、そのフォルダーの隣に空のファイル$AGENT_TOOLSDIRECTORY/Python/3.12.10/x64.completeを置くと、入った印になります。バージョンのフォルダー名は3つの数字すべてが要ります。 - ふつうに
/usr/binやC:\Program Filesに入れた Python はツール キャッシュにないので、タスクには見えません。上の並びに写すか、タスクを使わずにスクリプトのステップでその Python をパスで呼びます。 - エージェントがインターネットにつながらないか、そのシステムがレジストリのマニフェストにないなら、
disableDownloadFromRegistry: trueにします。ダウンロードを待たずに、キャッシュのバージョンの一覧つきですぐ失敗します。
PyCharm と IntelliJ IDEA で Azure DevOps のプルリクエスト
Azure DevOps Pull Requests は、JetBrains IDE 2024.1 以降と Android Studio で動く Lesstep のプラグインです。git のリモートから組織・プロジェクト・リポジトリを読み、あなたのレビュー待ちのプルリクエストを IDE のツール ウィンドウに並べます。Azure DevOps Services でも Azure DevOps Server でも動きます。プルリクエストのブランチ ポリシーを状態つきで見せるので、通っていない必須のビルドがプルリクエストの隣に出ます。Pro なら、失敗したビルド ポリシーや期限の切れたビルド ポリシーをそこからもう一度動かせます。レビューの受信箱は無料、投票・コメント・完了・作成は Pro（30日の無料試用つき）。
Azure DevOps と Azure Pipelines は Microsoft Corporation の商標、GitHub は GitHub, Inc. の商標、Python は Python Software Foundation の商標、PyCharm と IntelliJ IDEA は JetBrains s.r.o. の商標です。このページはそのいずれとも提携しておらず、承認も受けていません。
ほかに：Azure Artifacts からの pip の 401 · ホストされたエージェントで No space left on device · PyCharm で Azure DevOps のプルリクエスト · English