Use Python Version task

Azure Pipelines

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

Demands

None

Prerequisites

  • A Microsoft-hosted agent with side-by-side versions of Python installed, or a self-hosted agent with Agent.ToolsDirectory configured (see FAQ).

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.

YAML snippet

# Use Python version
# Use the specified version of Python from the tool cache, optionally adding it to the PATH
- task: UsePythonVersion@0
  inputs:
    #versionSpec: '3.x' 
    #addToPath: true 
    #architecture: 'x64' # Options: x86, x64 (this argument applies only on Windows agents)

Arguments

Argument Description
versionSpec
Version spec
(Required) Version range or exact version of a Python version to use.
Default value: 3.x
addToPath
Add to PATH
(Required) Whether to prepend the retrieved Python version to the PATH environment variable to make it available in subsequent tasks or scripts without using the output variable.
Default value: true
architecture
Architecture
(Required) The target architecture (x86, x64) of the Python interpreter. x86 is supported only on Windows.
Default value: x64

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

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

output variable

Remarks

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 defined in PEP 394. For example, for Python 3.7, python3.7 is the actual interpreter. 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.

Open source

This task is open source on GitHub. Feedback and contributions are welcome.

FAQ

Where can I learn more about tool installers?

For an explanation of tool installers and examples, see Tool installers.

Do I need an agent?

You need at least one agent to run your build or release.

I'm having problems. How can I troubleshoot them?

See Troubleshoot Build and Release.

I can't select a default agent pool and I can't queue my build or release. How do I fix this?

See Agent pools.

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

The desired Python version will have to be added to the tool cache on the self-hosted agent in order for the task to use it. Normally the tool cache is located under the _work/_tool directory of the agent or 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, concrete example, here is how a completed download of Python 3.6.4 for x64 would look in the tool cache:

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

For more details on the tool cache, look here.

In order that your scripts may work as they would on Microsoft-hosted agents, we recommend following the symlinking structure from PEP 394 on Unix-like systems.

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