Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

Plugin Information

View Version Number on the plugin site for more information.

This plugin is up for adoption. Want to help improve this plugin? Click here to learn more!

This plugin creates a new version number and stores it in the environment variable whose name you specify in the configuration.


In many cases, the Jenkins build number isn't rich enough to express the information you'd like the version number to have, and generating externally (as part of the build) may not be an optimal solution. This plugin allows you to generate a version number that contains much more information.

Project start date

The version number system has the concept of builds per day / week / month / year / all time. Each of these is the calendar day / week / month / year; that is, all builds in October will have the same build month, all builds in 2009 will have the same build year. These are based on the project start date, which is one of the user-configurable options.

Version Number Format String

The version number format string is processed to create the version number that's stored in the named environment variable. Every character in the version number format string is passed through to the final version number, with the exception of variables enclosed in ${}. For example, the version format string 1.0.${BUILDS_THIS_YEAR}, if this were the 10th build this calendar year, would return 1.0.10.

The following are valid variables for use in the version number format string:




Takes the second argument and returns a java-formatted date string for the given build date. For example, ${BUILD_DATE_FORMATTED, "yyyy-MM-dd"} would return the date (and not the time) as something like 2009-10-01. The date format string must be surrounded by quotes, and any whitespace within the format string is significant.


With no arguments, it just returns the day of the build as an integer. If there is an argument, it takes the number of characters in the argument and uses that pad the date string. For example, if it's the third of the month, ${BUILD_DAY} would return 3, ${BUILD_DAY, X} would return 3, and ${BUILD_DAY, XX} would return 03.


Returns the week, with the same argument convention for BUILD_DAY


Returns the month, with the same argument convention for BUILD_DAY


Returns the year, with the same argument convention for BUILD_DAY


Returns the number of builds that have happened today, including this one. This resets at midnight. The argument convention is the same as for BUILD_DAY


Returns the number of builds that have happened this week, including this one. This resets at the start of the week. The argument convention is the same as for BUILD_DAY


Returns the number of builds that have happened this month, including this one. This resets at the first of the month. The argument convention is the same as for BUILD_DAY


Returns the number of builds that have happened this year. This resets at the first of the year. The argument convention is the same as for BUILD_DAY.


Returns the number of builds that have happened since the project has begun. This is distinct from the hudson build number, in that it can be reset periodically (for example, when moving from 1.0.${BUILDS_ALL_TIME} to 2.0.${BUILDS_ALL_TIME}, and can be configured to start at an arbitrary number instead of the standard begin date.


The number of months since the project start date. This is strictly dependent on the month of the current build and the month of the project start date; if the project was begun October 31st and the build was November 1st, then this would return 1. If the project was begin October 1st and the build was November 30th, this would also return 1. The argument convention is the same as for BUILD_DAY.


The number of years since the project start date. Like MONTHS_SINCE_PROJECT_START, this is dependent only on the year;

(anything else)

Any other argument enclosed in ${} is replaced by an environment variable of the same name if one is available, or failing that, is just ignored. This can be used to integrate source control version numbers, for example.

Initialization Values

Before the build is started, the number of builds this year / month / week / day can be specified on the command line or via the job's plugin-configuration web-GUI. If they are specified, then they will override whatever values are currently in production. This allows you to migrate your version number from another system to Jenkins if you choose to do so.

Additionally, it is possible to automatically override the number of builds this year / month / week / day with values taken from environment-variables. Instead of just providing a simple number in the form-fields of the job's plugin-configuration which overrides the value for the next build (as described above), you can instead provide an environment-variable whose value will be extracted and used during the next builds. If it is not set or its value is not convertible to a positive integer (without loosing precision), the value of the previous build will be taken instead and increased by one (as is the standard behavior).


Version 1.9

  • Release Nov 17, 2017
  • Accepted merge-request #12. ("Adding functionality to limit the number of characters from a variable.")
  • Fixed bug JENKINS-18171. ("Version Number plugin doesn't increment build numbers after an unstable build.")
    • NOTE: This changes the checkbox for "skipping failed builds" (which actually meant to not increase the version-number if the former run was not successful) to a combobox of values.
      The transition works smoothly and does not change the former behavior. However, you should update the configuration of each job that had this checkbox checked (and save it)!
      (This assures that later updates of this plugin will not break your behavior due to this change.)


  • IMPORTANT: This might be the last update for this plugin in a long time, because I (user: bahadir) cannot maintain it any longer.
    Please volunteer to become the new maintainer of this plugin!

Version 1.8.1

  • Release Oct 11, 2016
  • Fixed bug JENKINS-26729. ("Endless loop when evaluating environment variables")

Version 1.8

  • Release Oct 11, 2016
  • Pipeline-jobs now allow overriding values of BUILDS_ALL_TIME etc. by environment variables (or fixed values), too, similar to Freestyle-jobs.
    (Use variables overrideBuildsToday, overrideBuildsThisWeek, overrideBuildsThisMonth, overrideBuildsThisYear, overrideBuildsAllTime.)
  • Fixed minor bug JENKINS-15371. ("Displayed Build version does not interpret parameters.")
  • Added minor logging.

Version 1.7.2

  • Release Aug 22, 2016
  • Fixed a regression-bug. JENKINS-36831. ("Regression breakage in version number after upgrade.")

Version 1.7.1

  • IMPORTANT: Lost in transaction. Update to version 1.7.2!

Version 1.7

  • Release Jul 11, 2016
  • Added feature JENKINS-34829. ("Pipeline-Support for Version Number Plugin.")
  • Fixed some XSS-vulnerabilities.
  • Minor corrections / changes (of typos, formatting etc.).
  • Updated minimal required Jenkins versions to 1.625.3.
  • Updated minimal required Java-version to 7.
  • IMPORTANT: This version has a regression-bug. Update to version 1.7.2!

Version 1.6

  • Release Oct 26, 2015
  • Support for BUILD_WEEK and BUILDS_THIS_WEEK.
  • Added feature JENKINS-29134. ("Overriding values of BUILDS_ALL_TIME etc. by environment variables.")
  • Fixed issue JENKINS-30224. ("NPE thrown when a job uses an automatically installed JDK.")
  • Minor corrections / changes (of typos, formatting etc.).

Version 1.4

  • Release Dec 17, 2011
  • Display name for every build can now be set to the formatted version number generated by this plugin.

Version 1.3

  • Released Dec 21, 2009
  • Largely for compatibility reasons - was using rather old deprecated methods and wouldn't actually work with modern Hudson builds.


  1. Unknown User (zzstore)

    Since we now have the ability to modify the display name of every build, it would be great to have the ability to change the display name to the version number set by this plugin.

  2. Unknown User (gdumont82)

    I understand we can use the BUILDS_ALL_TIME token to get an incremental build number and reset it manually when we change the major or minor version, but it would be great if this could be automated. I mean having the BUILDS_ALL_TIME reset to one when one of the previous digits in the version string changes.

  3. Unknown User (jivesh)

    How can i set build number 3333 is dynamically changes when baseline the version. This value can be get from xml file. But how can i set it in environment variables. Please help if you have any idea.

  4. Unknown User (sheeyam)

    I have installed XCode plugin on Jenkins and figured out how to do the versioning.

    But my requirement is different. I have set marketing version as 00.001.$

    Unknown macro: {BUILD_NUMBER}

    . Let say its the 3rd build. It shows as 00.001.3 but what i need is 00.001.003. How can i acheive this?


    for Build Number 75 : it should be 00.001.075

    And for build number 300 : it should be 00.001.300

    1. Unknown User (shokkas)

      use  00.001.$

      Unknown macro: {BUILD_NUMBER,XXX}

  5. Unknown User (shokkas)

    We are using the 'Prefix Variable' setting of the plugin to reset the BUILDS_ALL_TIME automatically to 1 when the variable values changes (this is the Mjor.Minor.Patch part of the version for the build, stored in a persistent environment variable parameter).
    This works great as long as the parameter was set before the version number plugin ran its sequence.

    For maven builds, we are trying to get the Prefix Variable parameter from the POM file stored in the SCM (Git), however, though setting the parameter is possible like so, it has no effect on the already set version number.

    Is there a way to get the version number plugin to kick in AFTER SCM checkout happens?
    Or maybe be influenced from 'Prefix Variable' value change no matter when it happens?

    Thanks you,


  6. Unknown User (ivan_dubynets)

    seems doesn't work with JDK 1.6.

    I see the following line in log:ERROR: java.lang.NullPointerException

    do you have ideas how to fix it?

    1. Unknown User (pras_sawant)

      Hi Ivan

      did you find solution ... I am struggling with same error


  7. Unknown User (schniedergers)

    How exactly would I set the BUILDS_ALL_TIME to a given number (e.g. I want it to start at 30 instead of 1)?

    The page says "it can be reset periodically (for example, when moving from 1.0.${BUILDS_ALL_TIME} to 2.0.${BUILDS_ALL_TIME}, and can be configured to start at an arbitrary number instead of the standard begin date.". I tried via build parameter for BUILDS_ALL_TIME, and via "Prepare an environment for the run -> Properties Content", but it would continue to increment at the current number, not the one I supplied.

    1. Unknown User (schniedergers)

      Answering my own question - I overlooked the "Number of builds since the start of the project" option. That allowed me to set it to any arbitrary number.

  8. Unknown User (catonyx)

    At first, I thought I would have access to these any where such as using ${BUILDS_THIS_WEEK) in an EnvInject section. This doesn't seem to be allowed but could be very useful.

    So, I wonder if this could be extended to allow more than one variable creation in the same job. It would be way easier to have both 2015.11.01 and well as 20151101 in one job then trying to have both using other methods. Or have a short version 20151101 and a long version with the time attached such as 201511011301.

  9. Unknown User (sebastian_sl)

    I am setting the environment variable called build-version. I want to use it later for creating a github tag (with the git publisher plugin)

    Do you know how I can access build-version within jenkins? I tried $build-version but the variable is not recognised.

  10. Unknown User (pras_sawant)

    Getting ERROR: java.lang.NullPointerException when running on windows environment
    I have set up values under Create a formatted version number

    Environment Variable Name = SUB_VERSION
    Version Number Format String = $

    Unknown macro: {BUILDS_ALL_TIME , XXXX}

    Using Jenkins 1.652 and version number plugin 1.5

  11. Unknown User (lam2558)

    Can this allow me to modify the build name after it finishes? I if build fail, change name to something else then when it passes?

  12. Unknown User (simontaubert)

    This plugin comes in very very handy for us! Thank you!

  13. Unknown User (rstephens)

    I am using this plugin to simply create a build number formatted to 3 digits.

    I'm setting the build number variable as FORMATTED_BUILD_NUMBER, and I'm setting the format string as:


    I'm using the variable as a property in the command line of an MSBuild build, like this:


    However, I find that when I run my build, looking at the console output from MSBuild, it's not 3 digits:


    What am I missing?

    1. Unknown User (bahadir)

      The environment-variable BUILD_NUMBER does not come from this plugin. The ${..., XXX} syntax (probably) only works with the variables coming from this plugin.

      Only the following variables (and their ..._Z variants) support that syntax:

      BUILD_DAYThe day of the build.
      BUILD_WEEKThe week of the year of the build.
      BUILD_MONTHThe month of the build.
      BUILD_YEARThe year of the build.
      BUILDS_TODAYThe number of builds done on this calendar date.
      BUILDS_THIS_WEEKThe number of builds done in this calendar week.
      BUILDS_THIS_MONTHThe number of builds done in this calendar month.
      BUILDS_THIS_YEARThe number of builds done in this calendar year.
      BUILDS_ALL_TIMEThe number of builds done since the beginning of the project.
      MONTHS_SINCE_PROJECT_STARTThe number of calendar months that have elapsed since the project start date.
      YEARS_SINCE_PROJECT_STARTThe number of calendar years that have elapsed since the project start date.
  14. Unknown User (mikebayles)

    How do I set the initial value of BUILDS_ALL_TIME for a pipeline job? It worked well in freestyle, but I am struggling to convert to pipeline. 

    1. Unknown User (bahadir)

      Use the overrideBuildsAllTime parameter to override it.

      For example, you could do something like this:

          def version = VersionNumber projectStartDate: '1970-01-01', versionNumberString: 'build-${BUILDS_ALL_TIME}', overrideBuildsAllTime: '${NEW_BUILDS_ALL_TIME}';

      This will then override the BUILDS_ALL_TIME variable by the value of environment-variable NEW_BUILDS_ALL_TIME; if that environment-variable is not set it will not be overridden. These override* parameters exists for all other counters, too.


      1. Unknown User (mikebayles)

        So if I create a new environment variable called NEW_BUILDS_ALL_TIME, wouldn't I need to increment that on every successful build? Otherwise, VersionNumber will just use that every time, right?

        1. Unknown User (bahadir)

          That environment-variable should only be available if you really want to reset the value for that counter.
          If the environment-variable is not available ${NEW_BUILDS_ALL_TIME} will resolve to nothing. Therefore the parameter overrideBuildsAllTime will have an empty string as its value which will not override the normal value.

          You can use the example I provided in my former comment. Just make sure that your build-job only sets the environment-variable NEW_BUILDS_ALL_TIME (e.g. via "Prepare an environment for the run -> Properties Content") if you want to override the normal value.

          1. Unknown User (mikebayles)

            Ok that makes more sense. And then after the first successful build, I would then remove that environment variable?

            1. Unknown User (bahadir)


              Doing it this way you do not have to adjust the pipeline script anymore if resetting a counter. (This is particularly useful if your pipeline script is under version-control, because you do not have to spam the history with changes just for resetting a counter.)

              1. Unknown User (mikebayles)

                Thanks that is exactly my situation. Thanks for your help today!

  15. Unknown User (jholovacs)

    I'm missing something.  I installed this without issue, then I added versioning into my command line like so:

    dotnet build --verbosity minimal /p:AssemblyVersion=${BUILD_YEAR}.${BUILD_MONTH}.${BUILD_DAY}.${BUILD_NUMBER}

    When I run the build, it blows up with the following message:

    +dotnet build --verbosity minimal /p:AssemblyVersion=...45

    ...which is, of course, not a valid version number.

    What am I doing wrong?


    1. Unknown User (jholovacs)

      NM, I figured it out.  I thought I could call on the variables directly, but that does not appear to be the case.

      In the build configuration, I had to check the box for Create a formatted version number, and when the options expanded, I entered an Environment Variable Name of ASMBLY_VER.

      I then set the Version Number Format String to ${BUILD_YEAR}.${BUILD_MONTH}.${BUILD_DAY}.${BUILD_NUMBER}

      Then, in my Execute Shell build step, I changed my line to:

      dotnet build --verbosity minimal /p:AssemblyVersion=${ASMBLY_VER}

      ...and it worked as desired.

  16. Unknown User (stefans)


    I have this code block in a pipeline:

    ver1 = VersionNumber(
                versionNumberString: '${BUILDS_ALL_TIME_Z}',
                worstResultForIncrement: 'NOT_BUILT',
                versionPrefix: "someprefix.",
    ver2 = VersionNumber(
                    versionNumberString: '${BUILDS_ALL_TIME}',
                    worstResultForIncrement: 'NOT_BUILT',
                    versionPrefix: "otherprefix.",


    My problem is that only ver1 gets incremented on the next build and ver2 it's always the previous value. If I move the definition of ver2 before ver1 then ver2 will get incremented on the next build while ver1 will not.

    So is this a bug or using two calls in the same pipeline to VersionNumber not supported?

    You might ask why I need this - basically ver2 should be different from ver1 and keeps a history of "otherprefix." since it was added.

    1. Unknown User (pqc)

      Hello,I had the same problem,Do you have any solutions?