Gallery3:FAQ - Gallery Codex
Personal tools


From Gallery Codex


Installing and Upgrading

How do I install Gallery 3?

Start by reading the Gallery 3 Quick Start guide

I get an error 500 when I visit my Gallery 3 install for the first time

This probably means that your webserver doesn't support the "php_flag" command in the .htaccess file provided with Gallery 3. Solutions are:

  1. edit your php.ini file and set "short_open_tag" to 1
  2. edit your apache configuration file to allow per-directory overriding of Options or All (note that this has implications to broad to discuss here):
<Location "/gallery3/">
AllowOverride +Options

Also, check to ensure that mbstrings are enabled within your php.ini file. Edit your php.ini file and ensure that "extension=php_mbstring.dll" is uncommented.

Strange things just don't seem to work

Perhaps you are using Gentoo? You may need to add the following USE flags and recompile PHP to make this work: filter, json, simplexml, tokenizer, ctype

GraphicsMagick or ImageMagick are installed but I can't select them. What do I do?

They are probably installed in a path that Gallery 3 doesn't know about (for example, fink on OS X installs things in /sw/bin). To fix this, either add the path to the folder containing your toolkit to your system PATH variable or modify files where PATH is coded into Gallery 3. Currently:

modules/gallery/helpers/graphics.php:   putenv("PATH=" . getenv("PATH") . ":/usr/local/bin:/opt/local/bin:/opt/bin:/sw/bin");
modules/gallery/helpers/movie.php:      putenv("PATH=" . getenv("PATH") . ":/usr/local/bin:/opt/local/bin:/opt/bin:/sw/bin");

Please report back in the Gallery 3 forums with the path you had to enter, and we'll add it to the list.

How do I upgrade Gallery 3?

Currently we have 2 detailed sets of instructions for upgrading:

Upgrading from Gallery 2 to Gallery 3

Gallery 3 is actually a completely different application from Gallery 2, so there isn't an upgrade process as such.

Start by installing Gallery 3, then import your Gallery 2 items using the Gallery 2 Import Module which is included in the standard installation.


I have lost my admin password how to login?

If the email password recovery method does not work, then try:

File creation method

Create a file called <gallery3_dir>/modules/gallery/controllers/x.php and put this in it:

   class x_Controller extends Controller {
     public function login_as_admin() {

Then with your browser go to http://EXAMPLE.COM/gallery3/index.php/x/login_as_admin and you'll be logged in as an admin.
Then go to Admin > Users and change passwords till you're happy.
Don't forget to delete x.php!

DB admin method

Using your DB admin tool like , or your hosts DB admin tool

  • Log-into your DB and select the users table.
  • Change the password field on the admin user to:
  • You should now be able to login to your gallery with the admin user and password of 12345.
  • Once loged in go to Admin -> User/Groups -> and edit the users password.

Host specific issues the community has found

Why am I seeing errors about suhosin.session.encrypt?

Suhosin is a modification to PHP that adds extra security. Unfortunately, sometimes this security is a little bit overboard and interferes with features. Flash based uploaders which rely on sharing a session with your browser can't operate with certain Suhosin settings so you may see this error:

   Error: your server is configured to use the suhosin.session.encrypt setting from Suhosin. You must disable this setting to upload photos.

You have to fix this by changing your PHP configuration either for all of PHP, or just for your Gallery 3 install. If you want to change it site-wide, you can edit php.ini and put the following and restart Apache

 suhosin.session.encrypt = Off 

If you want to make this change just for a specific virtual host or directory, you can edit your Apache config file or .htaccess file and add this line in the appropriate virtual host block:

 php_flag suhosin.session.encrypt Off

On some hosts you have to comment out the line in .htaccess like:

 # php_flag suhosin.session.encrypt Off

If you can't use any of those methods, ask your host. Maybe you can change it by editing a local php.ini file, but you'll need to contact your host to find out exactly what to edit and where.

Why does it say I'm missing FFmpeg?

Gallery 3 attempts to use FFmpeg to examine uploaded movies. Without this, it can't tell what type of movie you just uploaded. FFmpeg is used to extract a frame from your movie to use as a thumbnail and to find the dimensions of the video for playback. Currently only FLV and MP4 files are supported in Gallery 3. You must install FFmpeg on your system in order to be able to upload movies with ease. If you don't have or can't get FFmpeg to work on your server, there are the community contributed modules, noFFmpeg and Video Dimensions as options.

Why am I seeing "Error 406"

mod_security is good to protect your website but it might cause some problems for certain web applications, especially in file uploads.

Add to your .htaccess file this line:

 SecFilterEngine Off

Why do I get a Error #2038 when I try to upload more than one item

Some servers have simultaneous upload limitations.

  • To overcome this; login, Click Admin -> Settings -> Advanced
  • Change the gallery simultaneous_upload_limit to 1 and save.
    • In PHP 5.2.12 and higher, the configuration variable max_file_uploads(ref: can be changed to configure how many files can be transferred simultaneously.
    • The limit configured in Gallery 3 should be less than or equal to the number configured in PHP 5.

If you have installed the "jhead" add-on module but jhead is not on the system, you will see error 2038 and possibly other errors, but no clear message in the log.

  • To correct this: Check to be sure "jhead" is installed on the server, using the operating system's software package manager.

If you are running Linux and SSL there is issues with version of Flash.

  • Upgrade your flash version.
  • Don't use self signed SSL certificates.

Why am I seeing a blank, or partially blank page?

There's probably an unexpected PHP error in the script that's not getting shown in the browser because we don't show inexplicable and confusing errors to end users. Try examining the debug info to see if that turns up a clue.

It could be possible also that the mysql password has changed. If so, you may then update the new password by editing the file your_gallery/var/database.php, at the line that displays: 'pass' => 'old_password'.

The installer does not warn you about special characters used in the DB password. Try to avoid using special characters like slashes when you set up the DB.

I get a The requested views, admin.html, could not be found error

In most cases this is because your host is using Apache 1.x that is not supported anymore.
More support for Apache 1.x and hosts that don't want to upgrade, try some community support:

How do I create a phpinfo page?

A phpinfo link is also very often needed. To create a phpinfo page on your server, do the following:

  1. On your desktop, create a new text file (on Windows, use NotePad, on any other operating system use whatever you can use to generate a plain text file)
  2. Open the text file and copy and paste the following:
    <?php phpinfo(); ?>
  3. Save the text file and rename it to phpinfo.php (or any other file with the extension .php)
  4. Upload the file to your gallery directory on the server
  5. Post a link to that file in the forums so we can see the environment/settings/restrictions.

Be sure to delete this file as soon as you have finished with it, as it is a security risk to make such information publicly-available.

How do I rebuild busted thumbs in G3?

In G3 builds up to RC1, when you batch add large images to G3 albums, sometimes the thumbnails are not created properly and show full size throwing off page formatting. To correct this, you can force a thumb rebuild for the images that are over sized. To do this, you can run a query set against your DB. Login to your SQL server and run the following queries:
1: (information query) select count(*) from items where thumb_height > 300;
1a: this will tell you how many thumbs you have that are over 300 pixels
2: (force thumbs as dirty) update items set thumb_dirty = 1 where thumb_height > 300;
2a: this will set thumbs over 300 pixels as dirty, forcing a rebuild.

additional info.. if you have table headers... add the header into the table selection.. for example, if your header is "gallery3" then your commands would be "update gallery3items set thumb_dirty = 1 where thumb_height > 300;" etc.

After you have run this command against your DB, login to Gallery and Admin -> Maintenance, Rebuild Images

Here is a handy module to rebuild items on a per album basis: rebuild_items

I deleted an album and now Gallery 3 is broken, what do I do?

There's a bug in the 3.0 release that causes Gallery to accidentally delete the first row in the items table by accident if you're doing multiple deletes at once. Luckily, this is easy to get back and the bug itself is fixed in the 3.0.1 release.

1: Run this SQL statement either in a MySQL client, or in PHPMyAdmin.

INSERT INTO items VALUES (1,NULL,NULL,UNIX_TIMESTAMP(),'',NULL,1,1,NULL,NULL,2,0,NULL,'','',1,NULL,NULL,2,NULL,'weight','ASC',1,NULL,NULL,'Gallery','album',UNIX_TIMESTAMP(),0,1,NULL,'1','1');

Note that if you're using a database table prefix, your table won't be called "items" it'll be "<prefix>items". Look in gallery3/var/database.php to see what your prefix is.

2: Immediately go to Admin > Maintenance and run the Fix Gallery task.

3: Upgrade to 3.0.1 (there's a link in the top right hand corner of ASAP.

Forum reference:

I get an "Oh no" message when trying to set permissions

Gallery protects your images using a system called mod_rewrite. This is a very powerful system, but it's not installed and configured properly on all systems. So when you edit permissions Gallery performs a quick check, doing the following:

  1. it creates var/security_test and tries to lock it down
  2. it then makes a request back to the web server, simulating a web browser and tries to get into that folder
  3. if it fails to get in, then your security works
  4. if it succeeds in getting in, then the security test failed and we put up a message

It's possible that on your system, #2 is failing because your server can't loop back onto itself. Sometimes this is because your server setup is complicated; some big hosting setups have very complicated innards.

This is very hard for us to detect in the code, so we err on the side of letting you know that something might be wrong. But you can always test it for yourself -- make an album private then log out and see if you can get to it, if you can't then it may just be that our detection code is unable to diagnose your setup correctly.

Things to check:

  1. Can you ssh to your server and then use telnet, curl or wget to see if you can get access to your website from on the server itself
  2. Make sure that the mod_rewrite module is enabled
  3. Make sure that in your Apache2 config you've set "AllowOverride FileInfo Options" on your virtual host

Why can't I upload big files (over a megabyte or two)?

The upload limits are enforced by the PHP / webserver configuration and not by Gallery 2/3.

In short: The administrator can change the upload_max_filesize and post_max_size directives in php.ini (the PHP configuration file). Also, you can try to override the system-wide default settings in a .htaccess file. Example, add this to your .htaccess file in your gallery/ folder to set a upload limit of 10 MegaBytes:

php_value post_max_size 10M
php_value upload_max_filesize 10M

This can result in a "Internal Server Error" (error status 500) on all your Gallery pages. If you get an error after this change, remove your changes. That means that your webhost doesn't allow such changes in .htaccess.

An alternative that works for some users: Add a php.ini file in your gallery/ folder with the following contents (notice the difference, here we have a = and no php_value):

post_max_size = 12M
upload_max_filesize = 12M

This may or may not work. You can check if these changes have actually changed your limits by browsing to your add items -> from browser page.

Changing to bigger value "memory_limit =" might also help. Note though that the memory_limit does not have to be exceed the file size of the files that are uploaded. memory_limit plays a bigger role when using GD as your image toolkit module. More on that topic can be found in other FAQ entries.

If you're using Apache 2, especially with something like RedHat, you may need to edit another directive, LimitRequestBody, as described in this forum post. Setting this directive to 0 (i.e. LimitRequestBody 0) will allow you to upload as big a file as you want (until you hit upload_max_filesize and/or post_max_size -- see the above email link for more information).

Dreamhost customers (and perhaps customers of other providers) should try searching for specific instructions on how to accomplish this. In the case of Dreamhost, they provide a wiki page describing exactly how to accomplish it here. I have personally tested it and it works. It boils down to creating a cgi-bin directory, copying their cgi php handler and setting it to be your default php handler. They also provide information on how to create a script that keeps php.ini and php.cgi up to date, but with your settings instead of theirs.

The default Apache configuration on Debian Lenny: put something like this into your Apache configuration if you are using G3:

   <Directory /var/www/gallery3/>
   AllowOverride All


Are my photos secure? They're right there on my website!

In Gallery 2 we recommended that your images should NOT be in the document-root. But in Gallery 3, the default location is in "gallery3/var/albums" which is freely available on your website. So this means that your photos aren't secure, right?

Wrong! You have full photo security and with Gallery 3 you also get super fast performance. Any photos that are visible to all users are unprotected. But once you mark an album as hidden to guests, we drop a special .htaccess file in with your photos that locks it down like Fort Knox. There are separate permissions for the original image, the resized image and the thumbnail each. This approach makes Gallery 3 faster and lighter without sacrificing security. Pretty cool, huh?

How can I move my gallery installation from one server to another?

The only important files are those in the var folder, the database, the rest can be freshly replaced with fresh releases from Gallery. Here is the basic outline, check out this

* NOTE * Also remember to account for any modules you may have installed yourself - write them down so you can add them back to your new gallery location, or copy them over to your new gallery location.

user guide for lots of detail.

  1. Export your database from server to disk using phpMyadmin or mysqldump
  2. FTP all your gallery files to your local hard drive and then to the new server (or directly from old server to new server if possible)
  3. Set up a new database for gallery at your new server (usually using a control panel)
  4. Edit the database settings in your var folders database.php file
  5. Import your database from disk to new server's new database

My Gallery 3 is very slow

  • Don't run Galler3 on a network file share.
    • Don't reference it through the network share route

I want to move my /var directory

Make sure you understand that your items are secure using permisisons:
Are my photos secure? They're right there on my website. But if you still want to move it:
use symlink or
Edit index.php in the gallery3 root directory and find:

    define("VARPATH", realpath("var") . "/");

Change "var" to "/path/of/your/choice". If you upgrade to a later revision of Gallery 3, you will need to make this edit again at that time.

As of version 3.0.1, the gallery installer does not read local.php, so you will either need to install with VARPATH in the default location and move later, or edit installer/index.php to define your alternate path as described above.

Where's feature X? It's really important to me!

Out of the box, Gallery 3 is not all things to all users. But never fear! We've created a module API so that crafty developers can add their own features to it. And they've added a bunch. Learn how to download and install new modules.


How do I add the Development module

The module is in the gallery3-contrib repository. One way is to use git clone to have that repository beside my gallery3 repository. For example, have the Gallery 3 installation in ~/home/public_html/gallery3 and the contrib repository in ~/home/public_html/gallery3-contrib Now in gallery3/modules create a symlink "ln -s ../../gallery3-contrib/modules/developer developer". Now edit gallery3/.git/info/exclude and add the line "modules/developer", which tells the gallery3 git repository to ignore the modules/developer directory. Now install the developer module just like any other module.

How do I see debug information?

By default, Gallery 3 ships in production mode. This means that if something goes horribly wrong, we don't show it on your site since that can leak confidential information about your site works. There are two main places where you can look to find out what's going wrong:

  1. gallery3/var/logs contains a set of log files where Gallery 3 dumps out debug information when it detects that something went wrong
  2. your Apache 2 log files. The location for these files varies, but often times it's in /var/logs. If you can't find this file, please contact your system administrator

You can also take Gallery 3 out of production mode so that you see error messages directly in your browser. The easy way to do this is to create a file in your gallery3 directory called local.php containing these lines:

<? defined("SYSPATH") or die("No direct script access");
ini_set('display_errors', true);

After creating this file, try your operation again and you may see the actual error appear in your browser. Remember to delete or rename this file when you're done! It's not a huge security leak, but there's no point in showing application errors to your users.

If you see a warning like Warning: date_default_timezone_get(): It is not safe to rely on the system's timezone settings then in all likelihood your version of PHP is misconfigured. Instruct your sys admin to set the date.timezone PHP config value (see

Why doesn't Gallery 3 use the Smarty template engine?

Why did you choose Kohana?

We evaluated many PHP frameworks:

We even evaluated one non-PHP framework: Django:

Our evaluation criteria:

Some discussion about why use a framework at all as opposed to a home grown one:

Ultimately our decision was Kohana:

Why do you use PHP's short open tags?

Short open tags are considered harmful by some, but they result in much tighter syntax in our PHP based templates. Here are some possible ways to print 'Hello World' in different template systems:

   PHP long tags: <?php echo $Hello_World ?>
  php short tags: <?= $Hello_World ?>
             ASP: {% $Hello_World %}
          Django: {{Hello_World}}
          Smarty: {Hello_World} 

As you can see, PHP with long tags is the noisiest. The main reason for deprecating short tags is because the <? token conflicts with XML tags. In our case, this is highly unlikely to ever be a problem, and even if it is it's a vanishingly small edge case. We're optimizing for a good developer experience here by requiring them to type less to do more. If at some point PHP short tags goes away, we can pretty easily convert the entire app over to using long tags.

Short open tags will still be enabled by default in all future versions of PHP. While there was initially an idea to change this in PHP 6, plans have changed and short open tags are here to stay.