Azure Pipelines · Python · Checked November 7, 2026

Azure Pipelines: "Version spec ... did not match any version in Agent.ToolsDirectory"

The Use Python version task, UsePythonVersion@0, does not install Python from python.org. It looks in the agent's tool cache, the folder in Agent.ToolsDirectory, and if the version is missing it tries to download a build from the GitHub Actions python-versions registry into that cache. This error comes when the version was neither in the cache nor downloaded.

When the failing build is a pull request's build validation, the pull request waits on it: Azure DevOps Pull Requests, a plugin for JetBrains IDEs, lists the pull request's branch policies with their state in PyCharm or IntelliJ IDEA, and with Pro runs a failed build policy again once the fix is pushed. Get it on JetBrains Marketplace

What it looks like

##[error]Version spec 3.x for architecture x64 did not match any version in Agent.ToolsDirectory. The lines after it list the versions that are in the tool cache, under Versions in and the folder, then two hints, one for Microsoft-hosted and one for self-hosted agents.
If the task tried to download, a line before it says why that failed: Failed to download Python from the Github Actions python registry, Could not find Python matching spec ... in the python-versions registry, or Failed to download Python versions manifest.

What the task does

In the task's source (version 0.283), it first looks for a cached Python that matches versionSpec and architecture. If none matches and disableDownloadFromRegistry is false, the default, it downloads from actions/python-versions and looks again. Only when both fail does it stop with this error.
The registry has builds only for the systems in its versions manifest, the task says the download does not work through a proxy, and without the githubToken input the requests are anonymous and can hit GitHub's limit for anonymous downloads.
Microsoft's page for the task still says downloading is not supported on self-hosted agents; the task's code tries the download on any agent, so a self-hosted agent with internet access and a supported system can get there too.

On Microsoft-hosted agents

The images cache a few Python versions: on ubuntu-24.04 and windows-2022 today, 3.11, 3.12, 3.13, 3.14 and 3.15 (their readmes in the runner-images repository). Any other version goes through the download.
Use a minor version such as '3.12' rather than an exact patch: the cached patch changes with each image update, and the task warns that exact versions are not recommended.
When the download fails on anonymous limits, pass a token: a GitHub personal access token kept in a secret variable, as githubToken: $(GITHUB_TOKEN). It only reads a public repository.
Microsoft's page for the task says the hosted Windows agents have both x86 and x64 builds, and the Linux and macOS agents do not, so architecture: 'x86' works on Windows only.

- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.12'
    githubToken: $(GITHUB_TOKEN)

On a self-hosted agent

Put Python in the tool cache yourself, in the layout from Microsoft's page for the task: $AGENT_TOOLSDIRECTORY/Python/3.12.10/x64/ holds the unpacked Python, and an empty file $AGENT_TOOLSDIRECTORY/Python/3.12.10/x64.complete next to that folder marks it as installed. The version folder needs all three numbers.
A Python installed the usual way, in /usr/bin or C:\Program Files, is not in the tool cache, so the task does not see it. Either copy it into the layout above, or skip the task and call that Python by its path in a script step.
If the agent has no internet access, or its system is not in the registry's manifest, set disableDownloadFromRegistry: true so the job fails right away with the list of cached versions instead of waiting on a download.

Azure DevOps pull requests in PyCharm and IntelliJ IDEA

Azure DevOps Pull Requests, a plugin by Lesstep for JetBrains IDEs 2024.1 or later and Android Studio, reads the organization, project and repository from your git remote and lists the pull requests that wait for your review in an IDE tool window, on Azure DevOps Services and on Azure DevOps Server. It shows the branch policies of a pull request with their state, so a required build that has not passed is next to its pull request, and with Pro you run a failed or expired build policy again from there. The review inbox is free; voting, commenting, completing and creating are Pro, with a 30-day trial.

Get it on JetBrains Marketplace

Azure DevOps and Azure Pipelines are trademarks of Microsoft Corporation; GitHub is a trademark of GitHub, Inc.; Python is a trademark of the Python Software Foundation; PyCharm and IntelliJ IDEA are trademarks of JetBrains s.r.o. This page is not affiliated with or endorsed by Microsoft, GitHub, the Python Software Foundation or JetBrains.

More: pip 401 from Azure Artifacts · No space left on device on a hosted agent · Azure DevOps pull requests in PyCharm · 日本語