PmWiki is designed to make it easy to upgrade the PmWiki software without affecting your existing data files or installation. For most upgrades, you simply copy the files in the new release over your existing installation.

Note for PmWiki 1.0 sites: Upgrading from 1.0.x to 2.0 requires more than simply copying the 2.0 software over the 1.0 installation. See PmWiki:Upgrading From PmWiki 1 for more details.

To upgrade PmWiki:

1. Read the release notes

If you're upgrading to a new major release (a release where the second number changes, as in going from 0.5.27 to 0.6.0), then carefully read the ReleaseNotes before performing an upgrade to see if there are any significant changes or preparation tasks that must be handled before performing the upgrade. Upgrading from a beta version of 2.0 is quite easy, but taking a look at the 2.0 ReleaseNotes doesn't hurt.

2. Backup

It's always a good idea to have a backup copy of your existing PmWiki installation before starting. You can copy the entire directory containing your existing installation, or you can just make copies of the wiki.d/ directory and any other local customization files you may have created (e.g., config.php, localmap.txt, etc.).

3. Download and extract

Download the version of PmWiki that you want from the download page.

Extract the tar image using tar -xvzf tgzfile, where tgzfile is the tar file you downloaded above. This will create a pmwiki-x.y.z directory with the new version of the software.

4. Copy

Copy the files in pmwiki-x.y.z over the files of your existing PmWiki installation. For example, if your existing PmWiki installation is in a directory called pmwiki, then one way to copy the new files over the existing ones is to enter the command:

Note that BSD systems will not have the -a option as a command-line argument for cp, but that's okay, since it's just shorthand for cp -dpR, so use that instead of -a.

On (some) FreeBSD servers and Mac OS X systems you need to use

5. Update customisations and recipes

That's it! Your base PmWiki installation is complete.

Now use the PmWiki:Site Analyzer to determine which recipes could be updated to the most recent version.

Unless you have made customizations to the pmwiki.php script or to the files in scripts/, your PmWiki installation should continue to run correctly! (Changes to these files are not recommended).

(Local customizations should go in local/config.php, pub/css, and pub/skins/yourskinname)

Note: Additional tips can be found on the PmWiki:Troubleshooting page.

    $WikiLibDirs = array(&$WikiDir,
      new PageStore('/path/to/existing/wiki.d/{$FullName}'),
      new PageStore('wikilib.d/{$FullName}'));