Skip to end of metadata
Go to start of metadata

Table of Contents

This page discusses how you upgrade from Hudson to Jenkins.

Migration is only supported from Hudson ≤ 1.395

Before you begin

Please make a backup, especially the Hudson home directory, that contains the most important information, such as jobs, configuration and build history. In the unlikely event that something goes wrong you can recover from the backup.

When you are actually migrating


Jenkins is basically a drop-in replacement to Hudson. It's the continuation of the same code base, in same package structure. There has been no major surgery since the rename, and the rename really only affected what's shown in the UI. As such, it understands the same set of environment variables, same system properties, and the same information in the home directory. So if you rename jenkins.war as hudson.war, and simply overwrite your hudson.war, the upgrade is complete.


Jenkins does not support cascading projects yet. See JENKINS-3157

Debian package

Current users of the Hudson debian package should follow the instruction here for the new users. When you do "apt-get install jenkins", it will uninstall the hudson package, transfer your /var/lib/hudson to /var/lib/jenkins.

  • A few users have reported losing their /var/lib/hudson data in the upgrade. Please make a backup before upgrading till the report can be sorted out.
    • Check your /etc/default/hudson for the HUDSON_HOME to backup
  • Note that Jenkins run as the jenkins user. If you have scripts and other automation that hard-codes the user name, they'll need to be updated.
    • If you are using the unix based authentication system, make sure that you add the jenkins user to the shadow group or you won't be able to log in.
  • If your /var/lib/hudson is big, it may take some time for the post-init script to do chown.
  • What used to be in /etc/default/hudson is now in /etc/default/jenkins. If you've made changes to this configuration file, you need to manually reflect those into /etc/default/jenkins.
  • If your HUDSON_HOME was not in /var/lib/hudson, you need to manually chown your HUDSON_HOME to the jenkins user and update /etc/default/jenkins.

If you don't want the jenkins package to touch /var/lib/hudson or if you'd like to keep the hudson user to run Jenkins, rename /var/lib/hudson to /var/lib/hudso_ before the jenkins installation, then after the package has finished installing, move /var/lib/hudso_ back to /var/lib/hudson and change /etc/default/jenkins to run as the hudson user.

RedHat/openSUSE packages

Current users of the Hudson rpm package should follow the instruction here (Red Hat) or here (openSUSE) for the new users. When you do "yum install jenkins" or "zypper install jenkins", it will uninstall the hudson package, transfer your /var/lib/hudson to /var/lib/jenkins.

See the caution about the Debian package above, with regard to what happens to /var/lib/hudson and the hudson user. In RPM packages, the configuration file is in /etc/sysconfig/... instead of /etc/default/....

There's a bug in the shutdown portion of /etc/init.d/hudson and Hudson fails to stop itself when it's removed. So check if the process is still running, and kill it if necessary before starting jenkins.

Installed as Windows service

If you've installed Hudson as a Windows service, stop the service and overwrite hudson.war with jenkins.war, and restart the service. No additional steps are necessary.

If you prefer, you can uninstall Hudson as a service (by executing hudson.exe uninstall which produces no output on successful execution), and re-install Jenkins as a service from GUI. During this process you'll be asked to specify the installation directory. Choose the same directory you've installed Hudson so that your data gets carried over.

Installed in servlet container

If you've installed hudson.war into a servlet container that you administer, download jenkins.war and deploy it as hudson.war.

If you prefer, you can just undeploy hudson.war and deploy jenkins.war. Jenkins recognizes HUDSON_HOME environment variable and system property, so it'll automatically find your existing data.


Jenkins pick up its home folder via various configuration parameters. Its precedence is as follows (higher first):

  1. JNDI environment entry called JENKINS_HOME
  2. JNDI environment entry called HUDSON_HOME
  3. System property named JENKINS_HOME
  4. System property named HUDSON_HOME
  5. Environment variable named JENKINS_HOME
  6. Environment variable named HUDSON_HOME
  7. System.getProperty("user.home")+"/.hudson" if it already exists
  8. System.getProperty("user.home")+"/.jenkins"

If you are thinking about upgrading to Jenkins but not ready to do so now

You can install Jenkins update center in your Hudson so that you get update notifications of future Jenkins releases. You can use the built-in upgrade mechanism in Hudson to smoothly migrate to Jenkins. To do so, go to "Manage Hudson" > "Plugin Management" > "Advanced" > "Update Site" and specify ""

After upgrading

While you are at it, please check this document and retrieve/create your account on, so that you can file issues, participate in Wiki, and so on.

  • No labels


  1. I'm on RedHat Linux and I'm just wondering if after the upgrade, will the process owner change from hudson to jenkins?  I have my private keys to the build nodes setup under the hudson id on the machine as well as some other processes.

    Update: So I see in the debian notes that it will indeed change the user to jenkins.  But, I can modify the /etc/sysconfig to run as hudson if I want after the fact.  Is that all I need to do if I'm ok with the move to /var/lib/jenkins?  Just change the user in that /etc/sysconfig?  That would be nice since I have private keys to remote nodes and even my maven repository info all configured in my hudson user's home dir.


    1. Yes, follow the notes in the Debian package section if you'd like to keep Jenkins run as the hudson user.

      1. If I'm on a Red Hat Linux machine and I've used yum to install hudson originally, can I just download the jenkins.war and copy it over the existing war?  Where does the war file live in a standard yum install?  Or do I really need to use the yum install jenkins instructions in this case.

        Update:  Sorry, I see the hudson.war in /usr/lib/hudson

        Update:  In case this helps someone else:  I'm on Redhat Linux and I ended up downloading the war, renaming it to hudson.war and replacing the hudson.war in /usr/lib/hudson.  Then it self-deployed the war on startup of Jenkins just fine and I was able to keep my original directories and users.  Of course, I'll have to use this manual update method moving forward.  One issue I did run into was on my Windows slaves.  I couldn't get the nodes to startup if they were Windows.  I ended up temporarily switching the node configuration to the jnlp type and then using the jnlp installation on the remote node and selecting the "install as windows service" option in the pop-up window.  After that was done, I could go back and switch the node configuration back to the windows service type.  Everything is working great now.


        Robert Redd

  2. Hi everyone.

    Are there plans to modify the node names from job config files to replace hudson with jenkins ? Possibly this question has already been answered somewhere, but I just thought of asking it here since this wiki page talks of upgrade from Hudson to Jenkins.

    What I am referring to is (sample config.xml excerpt):

    Will <hudson.tasks.Ant> be the new way to go or should we replace it with <jenkins.tasks.Ant> ?

    Thanks in advance!

    Parag Doke

  3. Hello all,

    I just upgraded my CI servers to Jenkins and I have to say the transition was very smooth - no problems.

    Great work to everyone involved.

    - Kevin

  4. We had hudson instance with large number of projects and decided to use jenkins. We referred this wiki page to upgrade from Hudson to Jenkins. We didn't face any issues, it works well.

  5. A month or two ago we migrated from Hudson to Jenkins, and everything went as smooth as can be. I am currently on Jenkins version 1.409.1 and being curious as to why I had not seen any options to upgrade to a newer version on the "Manage Jenkins" page went to your Changelog page to check and found numerous other releases had followed. I went to the Advanced Tab in the Plugin Manager to see if I could trigger a check for a new release manually, but I still only see the option to downgrade back to 1.395.1 and no other choices. All my plugins have been upgraded to the lates versions Jenkins offered, but this also still has not allowed me to get the option to upgrade to any newer versions of Jenkins. Am I missing something?

  6. I'm no expert,but I guess that this is because 1.409.1 is the 'long-term support release'.  1.409.1 is the latest release on that 'branch'.

  7. Simply replacing the hudson.war with a jenkins.war file renamed as hudson.war does not works well when Hudson is installed as a windows service. The JAR is replacing correctly and Jenkins runs. However, if you try to upgrade Jenkins to a new version, it will "upgrade" to Hudson, effectivelly reverting the replacement. The problem is that the data about download locations for upgrade still points to hudson-ci. There is a simple way to fix this without reinstalling everything from zero?

    1. The short answer is that you just need to let it sit for a day, so that Jenkins will retrieve a fresh update metadata from our update center. At that point, your upgrade will correctly point to future Jenkins releases.

      There's a ticket filed in the JIRA tracking this. Thanks for reporting this.

  8. I Did this:

    ---> You can install Jenkins update center in your Hudson so that you get update notifications of future Jenkins releases. You can use the built-in upgrade mechanism in Hudson to smoothly migrate to Jenkins. To do so, go to "Manage Hudson" > "Plugin Management" > "Advanced" > "Update Site" and specify

    Now what?

  9. One gotcha I faced during the migration is the case of Hudson running in a servlet container like Tomcat. There are environment variables to point to the Hudson/Jenkins home directory (which is typically ~/.hudson for Hudson). Jenkins supports both HUDSON_HOME and JENKINS_HOME. When upgrading I renamed that variable from HUDSON_HOME to JENKINS_HOME (pointed to the same ~/.hudson dir). That caused Jenkins to ignore existing Hudson configuration (including all job setups). When I reverted that variable name back to HUDSON_HOME it worked correctly. Otherwise upgrade went smoothly without issues (even with plugins) - great job!

  10. I just upgraded from Hudson to Jenkins on Ubuntu 11.10.  The apt-get installer did not migrate /var/lib/hudson to /var/lib/jenkins, but that was easy enough to do manually.  The tricky part was that when I start Jenkins with

    service start jenkins

    It ignored /etc/default/jenkins and instead got defaults from /etc/init/jenkins.conf. The default values are fine unless you want to change the www prefix. The file format of /etc/init/jenkins is different from /etc/default/jenkins, so you cannot just copy /etc/default/jenkins over top of /etc/init/jenkins.conf.

  11. Unknown User (velleh)

    Hi everyone.

    I started with Hudson because I didn't know any better. ;) Now I want to migrate my Hudson 2.2.0 Builds to Jenkins but when simply replacing the .jar file won't work I get lots of errors and my builds are all gone. My Users and the Slave configuration are fine though.

    Is there a guide of some kind to help me migrate from a newer Hudson build to Jenkins? I'm using Windows on my master node.

  12. I successfully migrated from Hudson 2.2.1 to Jenkins 1.509. Here is the Ant script that I created for this:

    Make sure to read the description carefully!!

    1. Hello Joost, I tried migrating hudson 2.2.0 to Jenkins, but failed. Unfortunately I can't open the link you provided. Could you help to send your script to my mailbox: Thanks very much.

    2. A little bit updated script, at least supporting multiconfiguration projects and promoted build plugin

      still requires a lot of hand work, but mostly works for me for migration from hudson 3.2.1 to jenkins 1.595