Gallery1:FAQ - Gallery Codex
Personal tools


From Gallery Codex

The paths and URLs in this guide are examples. Be sure to replace them with the paths and URLs specific to your installation.


Getting Gallery

How can I get the latest version of Gallery?

There are two different 'latest' versions of Gallery. There is the version that has been released by the Gallery developers in a packaged format on the downloads page, and there is the source code which is available from Subversion on SourceForge. Since developers are continuously adding new features and tweaking the codebase, the Gallery packages will tend to be more stable than the version you'll get from SVN. However, the version in SVN will have more current bugfixes and neat modifications. The version in SVN is typically pretty stable, since the developers use it to power their own personal Galleries, but it is bound to have the occasional major glitch.

To get the stable release of Gallery, visit the Gallery Download Page

To get the SVN version of Gallery, see the next FAQ item

How can I get the latest SVN version of Gallery?

See Gallery:Using Subversion. SVN nightly snapshots can also be downloaded from

Troubleshooting Gallery

How do I run PHP as a CGI to avoid safe_mode restrictions?

Running PHP as a CGI is usually done when PHP is not available on your server (but you can execute cgi-bin scripts) or when the normal PHP installation is running in safe mode. Note that in order for this to work, your server must be configured to read .htaccess files, which your host can disable!

  • Obtain a CGI version of PHP for your platform. You can downloads PHP binaries for various platforms on the Gallery Download Page. If you can't find a binary for your platform, but you have access to compile programs, you can configure PHP with this configure line.

./configure --enable-force-cgi-redirect --disable-safe-mode --with-config-file-path=/usr/local/lib/php-cgi

Then run make. The resulting binary will be called php in the sapi/cgi/ directory of the PHP source. Please submit the binary to alindeman, so he can include it on the download page. Please only submit binaries that use that exact configure line, for consistancy reasons.

  • Upload the CGI version of PHP to the cgi-bin directory and call it 'php.cgi. Upload it in BINARY FTP mode.
  • Chmod php.cgi 755 (chmod 755 php.cgi)
  • Create a new directory in your webserver root called php-cgi
  • Create a new .htaccess file in your php-cgi directory and put the following lines in it:
RemoveHandler .php
AddType application/cgi-php php
Action application/cgi-php /cgi-bin/php.cgi

That should be it! Install Gallery in your php-cgi directory. Please note it is extremely difficult to provide support for this, because there are many things that can go wrong and it's hard to diagnose the problem; you're mostly on your own!

When I try to access my Gallery or the configuration wizard, I get a 500 Internal Server Error. What's up?

This is because your webserver doesn't allow you to use certain .htaccess overrides. The Gallery setup script tries to set some PHP settings, but this requires you to set AllowOverride Options FileInfo or disable the overrides. If you have access to your httpd.conf file, add this to it:

<Directory "/path/to/your/gallery/directory">
   AllowOverride Options FileInfo

If you don't have access to your httpd.conf, delete the .htaccess file (from the setup/ directory if the configuration wizard is throwing the error).

Alternately a php.ini file can be added to the gallery directory and the settings can be commented out in the .htaccess file and translated.

As an example, the value:

php_value post_max_size 20971520


post_max_size = 20971520

in the php.ini file.

I've installed Gallery and all seems well. But when I try to upload an image it says Unable to make thumbnail(0) or Invalid image. What gives?

This is a very common problem. It's usually because the image manipulation program isn't getting called correctly, and this can happen for a number of reasons. To diagnose the problem, follow these steps:

  • Verify that the binaries (NetPBM or ImageMagick) are installed correctly and are chmodded 0755 (including the directory they are in).
  • One common installation mistake is to put the executable in a path that contains spaces. This happens often on Windows, if either package is installed in Program Files. The executables must not be installed in a path that contains spaces.
  • Re-run the Configuration Wizard. On step 2, select the option to put Gallery into debug mode. Attempt to upload a picture using the web form interface, not the applet. There will be a whole lot more debugging messages now, and it will help to diagnose the problem. Possible issues are listed below:

If you see any of the following messages, the solutions are listed below:

  • Error in loading shared libraries: Indicates that your dynamic library loader can't find a library that it needs. On Linux you can add the directory containing the appropriate library to /etc/ and then run ldconfig -v as root to fix this. If you don't have root access to the server, either contact your host for help or download a new version of ImageMagick or NetPBM and use the new install instead.
  • Abort trap or Segmentation Fault or Cannot execute binary file: Probably means you installed the wrong binaries for your system (e.g. installed the FreeBSD binaries on a Linux system) or you uploaded the binaries in ASCII FTP mode instead of BINARY FTP mode.
  • Permission Denied: More than likely, your NetPBM/ImageMagick directory or the actual NetPBM/ImageMagick binaries are not chmodded 0755. It could also mean that your host has disallowed you from executing programs; if this is the case, you must talk to them in order to get it resolved.
  • /usr/bin/convert: Not a JPEG file: starts with 0x0a 0x4d (/home/uspalmer/public_html/gallery/AUTHORS): This is a bug that has been fixed with the latest version of Gallery, please upgrade.
  • /usr/local/bin/convert: no delegate for this image format (/home/sites/home/web/albums/album_01/IMGP0215.jpg): This means ImageMagick doesn't have the appropriate libraries to handle a type of image format (in this case JPEG). If you have root access, make sure the appropriate image libraries are installed or ask your host to verify this. If not, you can try using NetPBM from the Gallery Download Page, which has all major image formats already included.
  • Status: (expected 0): This means that Gallery is unable to get a status message from PHP, which it relies on. One possible solution is that your host has disabled some needed php functions. To determine if they have, create a PHP file containing
echo ini_get("disable_functions");

If the output displays exec, your host has disabled a vital function to Gallery. Gallery will probably not run on your host.

Whenever I try to upload an image in Gallery, I get all these errors about safe mode. How can I fix this?

This is an unfortunate situation, because Gallery cannot run in safe mode. You have three options, listed below (try them in that order).

  • Email your host nicely asking them to remove the restriction for you.
  • See the earlier FAQ item about running PHP as a CGI
  • Find another host that does not use safe_mode. See the Web Hosting Referral Page for hosts that definitely support Gallery.

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

Craig Goranson wrote a very informative email about how to fix this issue.

Gallery tries to override the upload_max_filesize and post_max_size directives in its .htaccess file. This means that changing the setting globally may still result in it being overridden at the .htaccess level, so you may want to just change the directive there instead of globally. Gallery tries to set both of the directives to about 20 megabytes, so this will only affect you if you're going to upload files over that size.

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).

When I try to click on the "login" link on the Gallery page, nothing happens (no window pops up). What's wrong?

The most common reason for this is that you have JavaScript disabled or limited in your browser. Make sure that JavaScript is allowed to open windows, or else you may not be able to login to Gallery.

The number two reason for this problem is that your login page has a slightly different hostname than the one you used for your gallery. You can check this by right clicking on the login page and selecting Properties to see what its URL is. The common cause for this is that you used a variation on the standard URL to get to your Gallery, and then the browser thinks that the JavaScript popup is actually on a different host and it causes a security exception when the popup tries to control the main window. For example, if you've told Gallery in the config wizard that your gallery is at and then you actually access the Gallery by going to (note the "www" is missing), you'll still see your Gallery, but you'll experience this problem. The solution is to pick one hostname and stick with it.

When I try to login, everything seems to go correctly, but Gallery doesn't log me in?

There could be a few reasons why this doesn't work. Here are some of them

  • Verify firewalling software (e.g. ZoneAlarm) are not interfering. You can test this by disabling them temporarily.
  • If you are on Windows, you need to edit your session.save_path directive in php.ini to a valid directory. This defaults to /tmp, which isn't a valid directory on Windows. Change it to a valid temp folder, such as c:\winnt\temp. Then restart your webserver.

If you don't have access to php.ini, add this to the .htaccess file in your gallery directory.

php_value session.save_path "c:\winnt\temp"
  • Locate the temporary directory specified in php.ini, or as specified in the paragraph above, and remove the sess_* files. If Apache/PHP leave stale session files in the temporary directory, errors can occur when trying to create the session, and not logging in is the symptom.
  • Make sure that the session.use_cookies setting is on in php.ini. It defaults to on, but your host may have turned it off. You can verify by visiting page in your browser. Search for that directive.
  • Verify that you're visitng your Gallery at the correct domain and subdomain you specified in your configuration — if your gallery is configured to live at, then visiting won't work. In this case, the cookies Gallery sets will be set to use only and your session won't be recognized at
  • Verify that your browser is configured to accept cookies. If you have this functionality turned off, please turn it back on, or Gallery will not work.
  • Visit in your browser. Refresh the page and see if the number increases. If it doesn't, you have a problem with sessions. If you have done all of the above steps, you may need to contact your host for help.

I can successfully upload photos, but when I look in my album all I see are broken image icons. Why?

You've specified an incorrect path to your albums directory in the config wizard. You can fix this by re-running the Configuration Wizard and correcting the Albums URL value.

Why do I get Failed opening 'html_wrap/inline_albumthumb.header.default'?

If you unzipped/untarred the Gallery script on a Mac running OS 9.2.1 or less (ie, non OS X), once its uploaded, three files need to be renamed. They are in the HTML_Wrap folder - inline_albumthumb.footer.default, inline_albumthumb.header.default, and inline_gallerythumb.frame.default. The last few characters at the end of these file names will get truncated on the Mac so Gallery won't be able to find them (there will be an error message above and below each photo). Adding the 't' at the end in FTP or Telnet will solve this. This is only a problem if its untarred/gzipped on a Mac. If they are unzipped on the server they will work fine. (Thanks James O'Donnell)

Why, when I try to upload images, does it say No images uploaded?

  • Verify it is not related to this earlier FAQ item
  • Verify the PHP directive upload_tmp_dir is set to a valid, writable directory. You can view what upload_tmp_dir is currently set to by navigating to
  • Your PHP configuration may have file uploads disabled. Navigate to If file_uploads isn't enabled (search for it on that page), then you won't be able to upload images to Gallery, and you should talk to your system administrator.

Error: Your Userfile is not writeable

See next topic. Solution is the same.

Warning: fopen(".../albums/team/album.dat.lock","a+")

This typically happens when your ISP makes a change in your environment (like upgrading PHP or moving things around) without telling you about it. In a nutshell, some of Gallery's files wind up being owned by the wrong user and their permissions become set such that Gallery can no longer write to them. I've never found this to be the result of a bug in Gallery. To fix this, you can change the permissions on your Gallery data files so that Apache can read the files again. This should only happen on Unix. If you have shell access, you can fix it like this:

cd /var/www/albums
cd ..
chmod -R 777 albums

If you don't have shell access, you can use your FTP client to recursively (every file and every directory) chmod the albums directory 777.

Why do I get the error Allowed memory size of Xxx bytes exhausted?

You are exhausting the available memory that PHP has access to. There are three work arounds:

1 - Edit the master php.ini - There is a config variable named memory_limit that by default is set to 8MB. Edit php.ini and increase it to a larger value (restart Apache afterwards).

2 - Edit .htaccess file - If you don't have access to php.ini then you can sometime edit / create a .htaccess file for your gallery directory. When adding that line to .htaccess, you must use a number, in bytes. For example, 8MB would be about 8000000 bytes. Sometimes you can't create a .htaccess file on a shared host and Apache will through an error message.

php_value memory_limit [new memory limit]

Sometimes you need to put:

<FilesMatch "\.(php|html?)$">
 php_value memory_limit 20M

3 - Edit the local php.ini - If you are on a shared host then sometimes you can't edit the master php.ini file. So you can can edit when the php code is parsed. To do this edit main.php and put the following at the start of the php.

ini_set ( "memory_limit", "20M");   

Please note that method 3 hasn't been approved by the developers yet. :)

Why, when I try to upload a .htaccess and chmod it with my FTP client, it "disappears"?

This is because on some FTP clients, the default setting is to hide files that begin with a dot. The file may actually be on the server, but your FTP client isn't programmed to display it. To make these files "reappear", you must change some settings. PixelPoet has written a tutorial for WS_FTP available here: Quick Tips for Chmod with WS_FTP. If you use CuteFTP, see thread in the forums. For WS_FTP, simply type "-a" (without the quotes) in the whitebox below MkDir on the remote (right) side of the program.

I can't extract a .tar.gz file on my Windows machine. Why not?

You need to use WinZip twice. (WinZip is a bit weird when it comes to .tar.gz archives).

  • Unzip, with WinZip, like you have done.
  • Rename the extracted file (in this example, netpbm1.1-gallery1.0-linux2.2-redhat6.2-intel) from netpbm1.1-gallery1.0-linux2.2-redhat6.2-intel to netpbm1.1-gallery1.0-linux2.2-redhat6.2-intel.tar.
  • Unzip once more

Why do I get errors like this: Warning: open_basedir restriction in effect. File is in wrong directory in /home/johndoe/public_html/gallery/platform/fs_unix.php on line 53?

This is caused by a PHP directive called open_basedir. Basically, your host has misconfigured this directive and not added the directory where Gallery is located to the directories where PHP can access and modify files. You'll need to contact them and ask them to add the directory where your website files are located.

Why do I get this error: Warning: exec() has been disabled for security reasons?

Gallery 1.x needs the exec() function to be enabled to execute ImageMagick or NetPBM. So its needed for any image manipulation action. As a result you can not upload any photos into Gallery 1.x. Please talk to your hoster about this.

How do I put my Gallery into debug mode?

Re-run the Gallery1:Configuration Wizard and change the flag on Step 2.

Which flag are you talking about? Why is it so difficult to write a simple answer to a real simple question? Which flag to set? Enough to set the debug level? Or do we have to enable syslog as well? After all, where do we have to expect the output?

I've set debug level to '3', paranoid mode and I can't see nothing at all. I expect output in my tmp directory but there's nothing. Do we need to restart Apache/IIS perhaps? Well, does not make a difference on my machine?

I have uploaded the NetPBM or ImageMagick binaries to my site, but I don't know the absolute path to specify in the configuration wizard. What do I do?

Upload a file named test.php to your NetPBM or ImageMagick directory. The contents of this file should be

print getcwd();

View this file via the web (for example: It will tell you the absolute path to specify.

When I try to enter an album, I get a 404 error. What's up?

mod_rewrite is not working correctly. Check to make sure mod_rewrite is installed and usable. Check to see if mod_rewrite is compiled into Apache

 httpd -l

This will list the modules compiled into Apache. If mod_rewrite is not in this list, check in your httpd.conf file for a line similar to the following

 LoadModule rewrite_module modules/

If you are sure that mod_rewrite is loaded, then in your httpd.conf make sure that

 AllowOverride FileInfo

is set for the directory where Gallery resides.

Otherwise you need to disable short_urls. Modify the following line in config.php:

$gallery->app->feature["rewrite"] = 1;

replace with

$gallery->app->feature["rewrite"] = 0;

I changed a value on Step 3 of the configuration wizard (or in config.php), but the change isn't taking effect. What's going on?

These values are defaults. They take effect for new top-level albums, but do not affect already existing albums. If you want to change the value of these parameters for already existing albums, edit each album's properties. You can access album properties by logging in as admin and going into the album in question. Select "properties" from the "admin options" pulldown. Then, in the popup window you will be able to change the properties for that album.

Can I host images on another server to conserve space?


Why do I get errors with email on Windows?

If you go to and it gives you the following errors:

"Error! sendmail_path not set"


"Error! SMTP not set"

You will have to do some changes to your php installation. If you get the "Error! sendmail_path not set" you can safely ignore it on Windows, since it disregards the sendmail_path anyway. To fix the other potential problem, locate your php.ini (probably under C:\Program Files\php or C:\windows), open it with a texteditor and find "mail function".

It should look something like this:

[mail function]
; For Win32 only.
; For Win32 only.
sendmail_from = 
; For Unix only.  You may supply arguments as well (default: 'sendmail -t -i').
;sendmail_path =       

Change SMTP to whatever SMTP server you can use that doesn't need authentication and sendmail_from to an email address. Example:

sendmail_from =

I've forgotten my admin password! How can I reset it?

  • Create a file named resetadmin in your /gallery/setup directory.
  • Visit the configuration wizard in your browser
  • Follow the instructions on the page
  • Specify a new password in step 2 of the configuration wizard

The Configuration Wizard will give you a special piece of information, and you will be required to edit the resetadmin file, add the string, save, and refresh your browser. This is a security measure to prove that you are an administrator.

Why do I get this error: Fatal error: session_start(): Failed to initialize storage module: user...?

Some other application has setup PHP to use a user-defined session handler. Gallery, however, doesn't run its own handler and relies on PHP to handle things. To correct for this, add this line to the end of your .htaccess file:

php_value session.save_handler "files"

This should fix it if you host allows you to edit PHP directives in .htaccess. If not, you may need to contact them to get it changed globally.

I need to remove my albums directory, but I can't since the webserver user owns the files. What can I do?

Bharat has made a simple script to chmod all the files in your albums directory 0777, so you can easily delete them with your FTP client. Download his script here: [1] ("Bharat's Cleanup Script"). Instructions are included in the top of the file.

Why is my Gallery blue?

As of Gallery 1.5, the CSS system has changed. There is a base.css which is loaded anytime. Then, there is screen.css which is loaded when you use a skin (or the default) and your gallery is not embedded in another program. Finally, there is embedded.css which loads when your gallery is embedded in another program. To change the color of your gallery, you can edit the appropriate CSS file or select a skin in the configuration wizard.

How do I use Gallery both from inside my LAN and the internet?

There are two ways to do this; both are shown below: The easiest way to do this is to use relative URLs in config.php. Note You will have to redo this each time you run the config wizard, since the config wizard won't accept relative urls. You need to edit config.php manually. There are two URLs in that file. Change each of them as follows:

From: To: /gallery /gallery/albums (change these URL's to match your Gallery setup)

The second method does not require any server-side changes, as the changes you make are made on the client. This may not be the most efficent solution, especially if you have many client computers.

You need to edit a file called HOSTS on your client machine. The HOSTS file is a ip-address to domain-name mapping file. Adding a line to this file, will make your client look for a local ip instead of an external ip, even if you use a fully qualified domain name.

Add a line similar to this:

This line will make all requests to (and request the server at (replace this with your server's real LAN IP address).

Depending on your client's operating system, the HOSTS file will be in a different place. Also note that on Windows clients, you will need to reboot the system for the changes to take place.

  • Windows 95/98/ME


Note this file in called hosts.sam. It must be renamed hosts for everything to work.

  • Windows NT/2000/XP Pro


  • Windows XP Home


  • Linux/Unix


How do I get Gallery to show a random photo/image on my website?

There is a script within the root of the gallery that does just that called block-random.php. So if your gallery was at, the script would be All you have to do is include that script into your code

<iframe src="" width="400" height="400" name="random-image"></iframe>

Or, alternatively:

<!--#include virtual="/gallery/block-random.php" -->

The iframe method will create an iframe with a fixed width and height. The include method avoids this. (Of course, you must have server-side includes enabled on your web server to use the include method.)

Why do I get the error: Warning: opendir(/var/www/watermarks): failed to open dir

This error may be caused by a faulty installation or upgrade, invalid permissions on a directory, or missing helper program. It indicates that you do not have the watermark feature installed or enabled properly. To fix this you should reinstall Gallery to the latest version or, if this is not an option or you would like to do without the watermark feature, simply find and comment as indicated the following lines in your /etc/gallery/config.php file.

 *$gallery->app->watermarkDir = "/var/www/watermarks";
 *$gallery->app->watermarkSizes = "0";

My Gallery gives an error when using turkish

Using Gallery with PHP5 and language is turkish gives an erro like this: Fatal error: Call to undefined method AlbumDB::numAccessibleItems()

The reason is a bug in PHP5. See

Solution: None for PHP5. For using Gallery in turkish, you need PHP4