Python Tool and Pipeline

A Jenkins plugin that automates standalone Python provisioning and runtime environment configuration across Windows, Linux, and macOS agents.

Similar to the NodeJS and Go tool plugins, this plugin enables Jenkins pipelines to dynamically provision specific standalone Python versions on-demand without requiring pre-installed system packages, package managers (apt, brew, choco), compiler toolchains, or administrator/root permissions.

• Zero Agent Prerequisites: Automatically downloads official, relocatable standalone CPython distributions from python-build-standalone.
• Native Astral uv & uvx Acceleration: Provision Astral uv on-the-fly (uv: true) for 10x to 100x+ faster virtual environments and package installations.
• Cross-Platform: Full support for Linux (x86_64, aarch64, armv7, ppc64le, s390x, musl), macOS (Intel, Apple Silicon), and Windows (x86_64, arm64, x86).
• Flexible Pipeline Step: withPython(...) supports dynamic version downloads, pre-configured tools, isolated virtual environments, CUDA GPU path injection, and corporate mirror URLs.
• Configuration as Code (JCasC): Fully configurable via jenkins.yaml with automatic tool installation.

In Python CI workflows, dependency resolution and package installation often consume 60% to 80% of total build time. This plugin integrates native Astral uv support (uv: true), replacing standard pip and venv operations with Astral's high-performance Rust toolchain.

Measured inside Jenkins CI across 5 workload tiers (3 iterations each):

Even on cold builds (clean agents without pre-cached wheels), Astral uv finishes package installations 1.5x to 3.6x faster due to parallel network streaming and non-blocking wheel unpacking.

• Sub-second Environment Setup: uv venv creates isolated virtual environments in ~10ms, providing clean isolation for every stage or test matrix run without performance penalties.
• Sub-second Repeat CI Builds: On warm caches, installing even 75+ heavy packages (numpy, pandas, scipy, scikit-learn) drops from 13.06s down to 0.12s (a 108x speedup).
• Drop-in Compatibility: Run standard requirements files via uv pip install -r requirements.txt, lockfiles via uv sync --frozen, or invoke ephemeral tools via uvx ruff check ..
• Persistent Workspace Cache: Supply uvCacheDir: '.uv-cache' to maintain a shared, content-addressable wheel cache across executor runs.

pipeline {
    agent any
    stages {
        stage('Build & Test') {
            steps {
                // Provisions standalone Python 3.12 and Astral uv, creating an isolated .venv
                withPython(version: '3.12', venv: '.venv', uv: true) {
                    sh 'uv pip install -r requirements.txt'
                    sh 'pytest tests/'
                }
            }
        }
        stage('Lockfile Sync & Ephemeral Tools') {
            steps {
                // Use uv sync for pyproject.toml projects and uvx for CLI utilities
                withPython(version: '3.12', uv: true, uvCacheDir: '.uv-cache') {
                    sh 'uv sync --frozen'
                    sh 'uv run pytest'
                    sh 'uvx ruff check .'
                }
            }
        }
    }
}

pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                withPython(version: '3.12.15', venv: '.venv') {
                    sh 'pip install -r requirements.txt'
                    sh 'pytest tests/'
                }
            }
        }
    }
}

pipeline {
    agent any
    tools {
        // References a pre-configured installation from Global Tool Configuration or JCasC
        python 'Python 3.12'
    }
    stages {
        stage('Test') {
            steps {
                sh 'python3 --version'
                sh 'pytest tests/'
            }
        }
    }
}

pipeline {
    agent any
    stages {
        stage('GPU Training') {
            steps {
                // Probes agent CUDA drivers, injecting CUDA_HOME, LD_LIBRARY_PATH, and PATH
                withPython(version: '3.12.15', cuda: true) {
                    sh 'python -c "import torch; print(torch.cuda.is_available())"'
                }
            }
        }
    }
}

pipeline {
    agent any
    stages {
        stage('Internal Mirror') {
            steps {
                // Download standalone Python and uv binaries from internal Artifactory/Nexus mirrors
                withPython(
                    version: '3.12.15',
                    uv: true,
                    mirrorUrl: 'https://artifactory.corp.internal/python-dist/',
                    uvMirrorUrl: 'https://artifactory.corp.internal/uv-dist/'
                ) {
                    sh 'uv pip install --index-url https://pypi.corp.internal/simple -r requirements.txt'
                }
            }
        }
    }
}

You can manage Python installations and automated Astral uv bundling declaratively using Jenkins Configuration as Code (jenkins.yaml):

tool:
  python:
    installations:
      - name: "Python 3.12"
        properties:
          - installSource:
              installers:
                - pythonStandalone:
                    id: "3.12.15"
                    installUv: true
                    uvVersion: "latest" # or pin a specific version, e.g. "0.13.1"
      - name: "Python 3.11"
        properties:
          - installSource:
              installers:
                - pythonStandalone:
                    id: "3.11.10"
                    installUv: true
      - name: "Python 3.12 (Internal Mirror)"
        properties:
          - installSource:
              installers:
                - pythonStandalone:
                    id: "3.12.15"
                    installUv: true
                    mirrorUrl: "https://artifactory.corp.internal/python-dist/"
                    uvMirrorUrl: "https://artifactory.corp.internal/uv-dist/"
      - name: "System Python"
        home: "/usr/bin/python3"

1. Navigate to Manage Jenkins → Tools.
2. Scroll to Python and click Add Python.
3. Configure the name (e.g. Python 3.12).
4. Under Install automatically, select Install Standalone Python from Astral-sh.
5. Select your desired Python version (e.g. 3.12.15).
6. (Optional) Check Install Astral uv alongside Python (and optionally set an Astral uv Version) to bundle uv and uvx.
7. Click Save.

For air-gapped Jenkins controllers without outbound internet access:

• Option 1: Place python-versions.json directly into $JENKINS_HOME/python-versions.json.
• Option 2: Launch Jenkins with the system property:

  -Dio.jenkins.plugins.python.versionsFile=/var/jenkins_home/my-custom-versions.json

• Option 3: Configure internal URL mirrors for dynamic catalog updates and binary downloads:

  -Dio.jenkins.plugins.python.versionsUrl=https://internal-artifactory.corp/python/versions.json
  -Dio.jenkins.plugins.python.mirrorUrl=https://internal-artifactory.corp/python-dist/
  -Dio.jenkins.plugins.python.uvMirrorUrl=https://internal-artifactory.corp/uv-dist/

The plugin automatically checks and caches new releases from astral-sh/python-build-standalone. Maintainers can also manually update the bundled catalog:

python scripts/update-python-versions.py

This plugin is licensed under the MIT License.