Gallery2:migration - Gallery Codex
Personal tools


From Gallery Codex

Migrating from Gallery 1 to Gallery 2

Read First

For optimum results, please read this entire page before starting, then follow these steps. Make notes along the way (esp. errors encountered) and make suggestions for the completeness of this document.

The cleanup script find_orphans and validate_albums are an important part of the pre-migration preparation. These scripts were introduced with version 1.5. If you are running a pre-1.5 version, please consider that upgrade first. Then come back and upgrade to v2.


Upgrading from Gallery 1 to Gallery 2 is a little different than just upgrading to a newer Gallery 1.x version. These are the steps that we'll walk you through:

  1. Prepare the migration (verify the integrity of your Gallery 1 installation and create a backup)
  2. Install Gallery 2 in another folder on the same server
  3. Prepare your Gallery 2 installation to handle all your Gallery 1 data
  4. Import your Gallery 1 data to Gallery 2
  5. Remove your Gallery 1 installation from the server
  6. (optional) Ensure your old Gallery 1 URLs still work with Gallery 2

Pre-Migration Prep

  1. Backup your existing Gallery v1 albums.
  2. Download the backup if you have not downloaded it already.
  3. Log into the admin account at your gallery website
  4. Run the find_orphans script on your Gallery v1 site Fix any problems that it finds. (Note: The find_orphans and validate_albums scripts do not exist prior to v1.5.)
  5. Run the validate_albums script in your Gallery v1 site ( Fix any problems that it finds, else the migration won't be successful.
  6. If these tools fail, either your g1 is broken or you do not have enough memory allocated to your g1. To increase the memory given to these gallery tools: add "php_value memory_limit 32M" to the ".htaccess" file in your gallery directory. Fix that first, then fix any problems found by these tools, then try to migrate.
  7. Rename your Gallery v1 application folder (likely '../gallery') to "g1" (We will use the original gallery folder for the Gallery v2 install). Modify your web server configuration to reflect the folder change if necessary. You may also need to modify your "g1" .htaccess file if you were using mod_rewrite for search-engine friendly URLs.
  8. Backup the 'config.php' in your g1 folder.
  9. Reconfigure your Gallery v1 install to reflect the folder change by going to Alternately, edit your 'config.php' and '.htaccess' so that your gallery will work in the new location. (see Notes below for lines to change in 'config.php')
  10. Visit every album in your Gallery v1 site. (optional)

Your Gallery v1 installation should now be bulletproof. Hooray!

...Time to move to Gallery v2.

Install Gallery 2

  1. Install Gallery v2 into a new folder called gallery (e.g. extract and rename gallery2 to gallery)
  2. Run the Gallery v2 installer. (see:Gallery2 Install Instructions ) ( For your storage directory choose a new, empty folder. DO NOT choose your Gallery v1 albums directory. We will import them later.
  3. Do not put your Gallery v1 albums into your Gallery v2 data directory. We will import them later.
  4. Login to Gallery v2 site using the admin user you created during install.
  5. Go to site admin.
  6. In site admin -> Plugins, deactivate GD unless you REALLY need it. GD uses a lot of memory and may interfere with the import of data from Gallery v1. see: Installing_an_Image_Processing_Library
  7. In site admin -> Plugins, activate the URL rewrite module. (Note: during install Gallery v2 directs you to lock down the directory access. You will have to grant access to .htaccess in order to complete this step)
  8. If you want to import user comments from Gallery 1, activate the Gallery 2 comment module.
  9. Install and activate the Gallery 2 Custom field and Hidden Items modules to ensure that all your Gallery 1 data is imported to Gallery 2. If it is missing go to --> plugins --> get more plugins to download and install.
  10. Ensure that the Square thumbs module in Gallery 2 is not active in case you don't want that all thumbnails are square (instead of having the same aspect ratio as the original photos).
  11. Ensure that the Plugin Migration is installed. If it is missing go to --> plugins --> get more plugins -> Migration --> and download this plugin.
  12. Create a test album.
  13. Upload images to that test album. Refresh the page to see what you uploaded.
  14. Verify that the images have uploaded correctly and that thumbnails were created.

If there are problems with your Gallery v2 installation, fix those problems first. Migration can only occur after Gallery v2 has been installed and is in working order.

Data Migration

Import Users

  1. Go to site admin -> import Gallery 1 (near the bottom of the Admin Option menu).
  2. On the Select Gallery page, enter Gallery v1 albums dir path (absolute filesystem path). (This is in your config.php for gallery1). Click Submit.
  3. On the Choose Objects page, select the users that you want to import from Gallery v1. Click Submit.
  4. On the Confirm Import page, verify that all of your users are listed on this page. (Note: Gallery 2 has a default 'guest' account, which is used for unregistered users. If your Gallery 1 installation also had an account named 'guest', then you should change the name of the Gallery 2 'guest' account to something else, for example 'g2_guest', prior to importing users.) Click Submit.
  5. On the Importing page there should be an orange progress bar. In the upper right hand corner there should be a memory display.
    1. Should the import fail at this point:
      1. Take note of the memory display in the upper right hand corner no matter what it says. Copy and paste this text somewhere.
      2. Note whether or not it says "Continue" below the orange bar.
      3. If any errors show up, please take note of those errors now. Copy and paste the full text somewhere.
      4. Refer to the troubleshooting part of this page now. Troubleshooting

Your users should be correctly imported now.

Import Album Data

  1. If everything went fine, click "import more data"
  2. You should end up on the Select Gallery page. Your path from last time should be available for you to click.
    1. Click it, then submit.
  3. On the Choose Objects page, select the albums that you want to import.
    1. If your items (photos) had Descriptions, for the "Set description" choose "Custom field" and enter "Description".
  4. Select a few albums to import as a test (this step will copy all these albums including all files). Click Submit.
  5. On the Confirm Import page, verify that all of your selected albums are listed. Click Submit.
  6. On the Importing page there should be an orange progress bar here. In the upper right hand corner there should be a memory display.
    1. Should the import fail at this point:
    2. Take note of the memory display in the upper right hand corner no matter what it says. Copy and paste this text somewhere.
    3. Note whether or not it says "Continue" below the orange bar.
    4. If any errors show up, please take note of those errors. Copy and paste the full text somewhere and refer to the troubleshooting section of this page. Troubleshooting
  7. If the import of these albums is successful, you can delete these albums from your Gallery v1 albums directory.
  8. Click "import more data" to continue to import until all your g1 albums have been imported. Import only a few hundred MB worth of photos at a time to prevent reaching the memory usage cap.
  9. If you plan on keeping your Gallery v1 site on-line, after the import completes, place the new .htaccess file into your old Gallery v1 albums/ directory.
    1. If there exists already a file with the name ".htaccess" in your Gallery v1 albums/ directory, replace it with the following .htaccess file
    2. If there's no .htaccess file in this albums/ directory yet, copy the following .htaccess file to this directory
    3. The new .htaccess file can be downloaded from "site admin" -> "Admin->import->Gallery 1" and it needs to be placed into your old Gallery v1 albums/ directory
    4. If you disabled gd before starting your import, re-enable it on the Admin->Modules page.

Preserving Gallery 1 URLs

All your Gallery 1 image and photo / album page URLs will still work after the migration to Gallery 2 if you follow these steps:

Keep the Migration Module

Never ever uninstall the Gallery 2 Migration module! This module remembers how to map your Gallery 1 URLs to Gallery 2 items / URLs. If this module has been uninstalled, all its data is lost and your Gallery 1 URLs will no longer work. Keep this module activated. If it's deactivated, URL forwarding won't work until you activate the module again.

We suggest you create a backup of your Gallery 2 database right after you're done with importing all Gallery 1 data.

Enable the G1->G2 URL Rewrite Rule

  • We assume you already installed and activated the URL Rewrite module.
  • Go to Site Admin -> URL Rewrite and enable the G1->G2 Mapping rule.
  • Don't forget to click Save :)

Add New .htaccess Files in Your Gallery 1 and Gallery 1 albums Folder

Follow the URL Redirection instructions that are shown on the Site Admin -> Import: Gallery 1 page once some albums have been imported.

  • Basically, you need to add a .htaccess file with the contents as shown on that page in your Gallery 1 albums/ folder such that Gallery 1 image URLs are forwarded to Gallery 2 and still work.
  • You can delete the contents of your Gallery 1 albums/ folder, but the folder itself and the new .htaccess must stay in place to keep the old URLs working.
  • If your Gallery 2 is installed in a different folder than your Gallery 1 used to be installed, you need to keep the old Gallery 1 folder in place (it can be empty) and you need to put the new .htaccess file in that folder to forward all album / photo page requests to Gallery 2.


  • You will likely need to increase the PHP memory size limit in order for the import to finish successfully. Setting memory_limit to 32M worked for a gallery with approximately 4000 images. This is usually the fault of gallery1's poor design. If you can set the memory limit to a higher value like 64M or 128M for the duration of the migration, please do so.

See: Gallery 1:FAQ Allowed Memory Size

  • Gallery v1 and v2 have different album and item metadata fields and field lengths. If you have relatively long summaries or titles, the default settings will likely truncate those. The import process allows you to change the mappings. The following mapping does a better job of preserving data than the defaults:
    • Filename -> Title
    • Caption -> Summary
    • Caption -> Description
  • Gallery v1's concept of "hidden" albums is available via the Gallery v2 hidden module. Be sure to install and enable the hidden module, and then verify the hidden attribute in each appropriate album's General tab.
  • Verify special permissions after importing. If there is any disparity from your gallery1 installation, please let us know.
  • The following Gallery 1.x config.php lines contain path entries, and will likely need editing in order to migrate
    • $gallery->app->albumDir
    • $gallery->app->photoAlbumURL
    • $gallery->app->albumDirURL
    • $gallery->app->movieThumbnail
    • $gallery->app->userDir

If you have any problems, please post any error given as text in a forum post in the gallery support forum with a title that includes one of these words: "import," "migrate", or "migration." Please read the entirety of this page and include all the information that we ask for in your post.


TAKE NOTES WHEN YOU RUN INTO PROBLEMS!!! Check the Support page for details on getting help with your Gallery installation. Reading through this section and providing the information listed below will help others help you faster.

  • If the migration stops at any point, please take note of the memory display in the upper right hand corner no matter what it says. Copy and paste this text somewhere.
  • If it stops, please note whether or not it says "Continue" below the orange bar.
  • If any errors show up, please take note of those errors. Copy and paste the full text of the errors somewhere.
  • If the migration simply stops at any time, copy the name of the album and/or item that was being processed when it stopped. Paste it somewhere.
  • If the import fails during a particular album, please try importing that album by itself first.
  • If the import fails on a particular image or movie, please make sure that the original version of the image or movie exists in your Gallery v1 site first.
  • If the image or movie exists, please download the original image or movie to your computer and upload it to Gallery v2 site outside of the import process. If it works or does not work, let us know.
  • If you do not have ANY memory amount shown there, you must share your browser version.
  • If you problem relates to incorrect non-ascii characters, please include the name of the character set from which you were importing.
  • Copy the names of all of the modules that you have active. Paste this somewhere.

Take all of the stuff that you have pasted and put it into your post.

It is very helpful to have a link to your Gallery v1 and Gallery v2 installations. It is not usually helpful to have a link to a zip file of anything unless we ask for it.

If you do not get an error, but get a blank screen, a timeout, or some other non helpful thing, please check your apache error log if possible and check for a line like 'memory allocation error, tried to allocate x bytes.' If you get such a line, please let us know. If you get any other line, please let us know.

  • If you use the option to enter Custom G1-fields for G2's "Summary" and "Description" entries, EXIF data might not appear in your G2, depending on your settings. If you absolutely want to see EXIF info, leave these options at "Blank", instead of "Custom fields" (at the expense of losing fields from your G1 of course).

PhpBB2->Gallery1 integration

As with all other integrated versions of Gallery 1.x the use of the migration code as is will result in the ownership of all albums and photos reverting to the admin account. Likewise all permissions are lost.

Luckily for phpBB2 users there's a mod/hack to allow you to migrate your phpBB2->Gallery1.x albums to phpBB2->Gallery2.x without losing ownership information.


Please note: The hack is still very much in BETA! and no warranty or support is implied or offered. So, you proceed entirely at your own volition. --Websnail 03:11, 18 April 2006 (PDT)