Four Practical Differences Between Jenkins Scripted and Declarative Pipelines

If you are reading this blog post, you are probably looking for the practical differences between scripted and declarative pipelines in Jenkins, and you have come to the right place.

Why are there two pipeline types? Scripted pipelines were the first implementation of pipelines‑as‑code in Jenkins, built on a Groovy‑based DSL that offers no fixed structure. Declarative pipelines, by contrast, enforce a predefined structure, which may feel restrictive but provides clearer conventions.

Both pipeline types can achieve the same goals, but the author recommends declarative pipelines for the reasons outlined below.

1. Code Validation When the Pipeline Starts

pipeline {
    agent any
    stages {
        stage("Build") {
            steps {
                echo "Some code compilation here..."
            }
        }
        stage("Test") {
            steps {
                echo "Some tests execution here..."
                echo 1
            }
        }
    }
}

Running this declarative pipeline fails early during validation, preventing the build from proceeding to any stage. The failure is shown in the log, saving time because no stages are executed.

node {
    stage("Build") {
        echo "Some code compilation here..."
    }
    stage("Test") {
        echo "Some tests execution here..."
        echo 1
    }
}

The equivalent scripted pipeline runs the same stages and steps but does not perform early validation, so the build proceeds until a later failure occurs.

2. Restarting from a Specified Stage

Declarative pipelines support a “restart from stage” feature. When the previous example is rerun, only the Test stage is restarted, skipping the already‑completed Build stage, which can be useful when only the test environment fails.

Scripted pipelines lack this built‑in restart capability; the entire pipeline must be re‑executed.

3. Options Block in Declarative Pipelines

Both pipeline types support timestamps, ANSI color output, and stage‑level timeouts, but declarative pipelines keep these options separate from the script logic.

pipeline {
    agent any
    options {
        timestamps()
        ansiColor("xterm")
    }
    stages {
        stage("Build") {
            options { timeout(time: 1, unit: "MINUTES") }
            steps { sh 'printf "\e[31mSome code compilation here...\e[0m\n"' }
        }
        stage("Test") {
            options { timeout(time: 2, unit: "MINUTES") }
            steps { sh 'printf "\e[31mSome tests execution here...\e[0m\n"' }
        }
    }
}

The equivalent scripted version expresses the same functionality with nested calls:

node {
    timestamps {
        ansiColor("xterm") {
            stage("Build") {
                timeout(time: 1, unit: "MINUTES") {
                    sh 'printf "\e[31mSome code compilation here...\e[0m\n"'
                }
            }
            stage("Test") {
                timeout(time: 2, unit: "MINUTES") {
                    sh 'printf "\e[31mSome tests execution here...\e[0m\n"'
                }
            }
        }
    }
}

4. Skipping Stages with a when Block

Declarative pipelines can conditionally skip stages using a when block. The example below runs the Test stage only when the environment variable FOO equals bar :

pipeline {
    agent any
    options { timestamps(); ansiColor("xterm") }
    stages {
        stage("Build") {
            options { timeout(time: 1, unit: "MINUTES") }
            steps { sh 'printf "\e[31mSome code compilation here...\e[0m\n"' }
        }
        stage("Test") {
            when { environment name: "FOO", value: "bar" }
            options { timeout(time: 2, unit: "MINUTES") }
            steps { sh 'printf "\e[31mSome tests execution here...\e[0m\n"' }
        }
    }
}

In a scripted pipeline the same conditional logic requires an explicit if statement, and the stage is not truly “skipped” but conditionally omitted:

node {
    timestamps {
        ansiColor("xterm") {
            stage("Build") {
                timeout(time: 1, unit: "MINUTES") {
                    sh 'printf "\e[31mSome code compilation here...\e[0m\n"'
                }
            }
            if (env.FOO == "bar") {
                stage("Test") {
                    timeout(time: 2, unit: "MINUTES") {
                        sh 'printf "\e[31mSome tests execution here...\e[0m\n"'
                    }
                }
            }
        }
    }
}

In conclusion, the four major differences—early validation, restart capability, options handling, and conditional stage execution—make declarative pipelines generally more convenient and less error‑prone than scripted pipelines.