UsePythonVersion@0 - Use Python version v0 task

Use this task to download or select a version of Python to run on an agent, and optionally add it to PATH.

Syntax

# Use Python version v0
# Use the specified version of Python from the tool cache, optionally adding it to the PATH.
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.x' # string. Required. Version spec. Default: 3.x.
    #disableDownloadFromRegistry: false # boolean. Disable downloading releases from the GitHub registry. Default: false.
    #allowUnstable: false # boolean. Optional. Use when disableDownloadFromRegistry = false. Allow downloading unstable releases. Default: false.
    #githubToken: # string. Optional. Use when disableDownloadFromRegistry = false. GitHub token for GitHub Actions python registry. 
    #addToPath: true # boolean. Add to PATH. Default: true.
  # Advanced
    architecture: 'x64' # 'x86' | 'x64'. Required. Architecture. Default: x64.

Inputs

versionSpec - Version spec
string. Required. Default value: 3.x.

Specifies the version range or exact version of a Python version to use, using SemVer's version range syntax. Learn more about SemVer.

disableDownloadFromRegistry - Disable downloading releases from the GitHub registry
boolean. Default value: false.

Disables downloading missing Python versions from the Github Actions registry. This boolean should only be true if using a local installation of Python.

allowUnstable - Allow downloading unstable releases
boolean. Optional. Use when disableDownloadFromRegistry = false. Default value: false.

Downloads unstable Python versions from the Github Actions Python versions registry if set to true.

githubToken - GitHub token for GitHub Actions python registry
string. Optional. Use when disableDownloadFromRegistry = false.

Specifies the GitHub token that enforces the anonymous requests limit in the Github Actions python versions registry. Leaving this empty may cause download failures. Not needed if using a local installation of Python.

addToPath - Add to PATH
boolean. Default value: true.

Prepends the retrieved Python version to the PATH environment variable to make it available in subsequent tasks or scripts without using the output variable.

architecture - Architecture
string. Required. Allowed values: x86, x64. Default value: x64.

Specifies the target architecture (x86 or x64) of the Python interpreter.

Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

This task defines the following output variables, which you can consume in downstream steps, jobs, and stages.

pythonLocation
The directory of the installed Python distribution. Use this in subsequent tasks to access this installation of Python.

Remarks

Use this task to download or select a version of Python to run on an agent, and optionally add it to PATH.

Prerequisites

• A Microsoft-hosted agent with side-by-side versions of Python installed, or a self-hosted agent with Agent.ToolsDirectory configured (see FAQ).
• Downloading python versions is not supported on self-hosted agents.

This task will fail if no Python versions are found in Agent.ToolsDirectory. Available Python versions on Microsoft-hosted agents can be found here.

Note

x86 and x64 versions of Python are available on Microsoft-hosted Windows agents, but not on Linux or macOS agents.

As of version 0.150 of the task, version spec will also accept pypy2 or pypy3.

As of version 0.213.1 of the task, version spec will also accept pypy2.x or pypy3.x.

If the task completes successfully, the task's output variable will contain the directory of the Python installation:

After running this task with "Add to PATH," the python command in subsequent scripts will be for the highest available version of the interpreter matching the version spec and architecture.

The versions of Python installed on the Microsoft-hosted Ubuntu and macOS images follow the symlinking structure for Unix-like systems that are defined in PEP 394.

For example, python3.11 is the actual interpreter for Python 3.11.

python3 is symlinked to that interpreter, and python is a symlink to that symlink.

On the Microsoft-hosted Windows images, the interpreter is just python.

For Microsoft-hosted agents, x86 is supported only on Windows. This is because Windows can run executables compiled for the x86 architecture with the WoW64 subsystem.Hosted Ubuntu and Hosted macOS run 64-bit operating systems and run only 64-bit Python.

How can I configure a self-hosted agent to use this task?

Important

Downloading python versions is not supported on self-hosted agents. You may only use pre-installed versions.

The desired Python version needs to be added to the tool cache on the self-hosted agent so the task can use it. Normally, the tool cache is located under the _work/_tool directory of the agent; alternatively, the path can be overridden by the environment variable AGENT_TOOLSDIRECTORY. Under that directory, create the following directory structure based off of your Python version:

$AGENT_TOOLSDIRECTORY/
    Python/
        {version number}/
            {platform}/
                {tool files}
            {platform}.complete

The version number should follow the format of 1.2.3. The platform should either be x86 or x64. The tool files should be the unzipped Python version files. The {platform}.complete should be a 0 byte file that looks like x86.complete or x64.complete and just signifies the tool has been installed in the cache properly.

As a complete and concrete example, here is how a completed download of Python 3.11.4 for x64 would look in the tool cache:

$AGENT_TOOLSDIRECTORY/
    Python/
        3.11.4/
            x64/
                {tool files}
            x64.complete

Learn more about the tool cache.

To make your scripts work as they would on Microsoft-hosted agents, use the symlinking structure from PEP 394 on Unix-like systems.

Also note that the embeddable ZIP release of Python requires extra configuration for installed modules, including pip. If possible, we recommend using the full installer to get a pip-compatible Python installation.

Requirements

Requirement	Description
Pipeline types	YAML, Classic build, Classic release
Runs on	Agent, DeploymentGroup
Demands	None
Capabilities	This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions	This task runs using the following command restrictions: restricted
Settable variables	This task has permission to set the following variables: pythonLocation, PATH
Agent version	2.182.1 or greater
Task category	Tool