Joomla Template Installation: Common Problems and Solutions

Getting a new Joomla template on your web server should be an easy task. You head over to your Joomla Administrator, go to the ‘Extension Manager’, select your template, and click ‘Upload & Install’. This article will provide you with solutions for the cases that the next screen after clicking that button doesn’t show a success message.

How to install a Joomla template?

In both Joomla 2.5 and Joomla 3 there are three different ways to install a Joomla template. All of them can be found in the ‘Extensions Manager’, which is conveniently located below the menu item ‘Extensions’.

Upload Package File

Installing a template using this method is actually pretty straightforward. You simply browse your computer for the template archive file (usually with a .zip suffix) and click the ‘Upload & Install’ button.

Install from Directory

To install a Joomla template using this method, you should first upload the desired template via FTP. The folder to which your template should be uploaded is the /tmp directory found in the root folder of your Joomla! installation. It has folders such as /administrator and /images on the same level.

Install from URL

If you want to install a template from another URL, you should use this method. Simply enter the URL where the template archive is found here and click ‘Install’. Beware that this technique relies on some PHP settings that might have been turned off by your server administrator.

Which one should I use?

In the vast majority of cases you’ll want to use the ‘Upload Package File’ option to get the desired template installed on your website. Only when that option isn’t showing the expected results (for example, you encounter an upload size limit), you should start looking at the other two options.

Troubleshooting template installation

Problem: After clicking ‘Upload & Install’ the page reloads but the template isn’t installed

You should check a few things to find out what might be causing this problem. First off, you should try to install another extension. Your best choice would be small sized extensions (low number of Kilobytes), and one that you know installs well on another website or server. Perhaps instead of a template you might want to try installing a component, module or plugin to see if that reaches a different result. If the problem persists, try raising your error reporting level (for example via ‘Global Configuration > Server’ to see if any errors are displayed before or after trying to install the template.

Problem: Error “JInstaller: :Install: Cannot find XML setup file” or “unable to find install package”

The first thing you should do when you encounter one of these problems is to check what type of file you are uploading. If you look at the file name, does it suggest that this is a valid template archive file? Does the file name consist of a pre-upload call to action, such as ‘unzip me first’? Once you’re certain this is the case and the template still won’t upload, try unzipping the archive on your local computer. When you look at the files within the template archive (and you compare it to another template that does successfully install on your website), does it seem off? Is there a templateDetails.xml file, and if so, does it have any content once you open it with a text editor?

Problem: Error “Warning! – Failed to move file”

This issue is very likely related to directory read/write permissions. Faulty permission settings are unfortunately a very common problem, but luckily, several solutions and workarounds are available. To ensure this is a directory permission related problem, first go to your Joomla Administrator, then in the horizontal menu click Site, then System Information. In the ‘Directory Permissions’ tab, Joomla will tell you whether it thinks it is able to write to the specified directories. If one or more directories are marked ‘Unwritable’, you’re potentially facing a problem with directory permissions.

The best solution to this problem is to make sure that all directories have proper owners and read / write / execute rights. By activating the Apache module suPHP (or have your host activate it), this is done automatically for you from now on. If you, or your host, are unable to do this, try looking (or asking) for other alternative solutions that have the same automatic effect.

Alternatively you could try to change the CHMOD settings of folders such as /templates and /tmp yourself. However, on most servers that are already facing problems with directory ownership, the only CHMOD setting that will actually work is 777. However, as outlined by Joomla! security expert Nicholas, the CHMOD setting 777 is should be avoided whenever possible because it creates severe security risks for your website.

A final resort would be to activate the FTP layer in Joomla. This can be done via the Server tab of the Global Configuration area in the Joomla Administrator. Do note that activating this setting is also known to create several security related problems. If you are facing problems with the activation of your FTP layer, check out this FTP layer troubleshooting guide.

Problem: Website is blank after clicking ‘Upload & Install’

When a blank screen is showing after uploading a template, there is usually a problem with the PHP upload settings and/or the error reporting. What very likely happens is that after the upload a fatal error is triggered by PHP, but the error is consequently hidden by the error reporting settings, which in combination causes a blank screen to show up. Try raising your error reporting level to ‘Maximum’ or ‘Developer’ (Global Configuration > Server) and see if any errors are shown now after you try to upload the template again.

Very likely an error is shown now related to the maximum file size that can be uploaded to this server. To change this, you should either raise the value for upload_max_filesize or post_max_size in the php.ini file. For either one of them, a value of 8MB should probably be sufficient. Don’t forget to restart the server after making your changes. If you don’t have access to the php.ini file on your server, you could try changes these values using your .htaccess file by entering ‘php_value upload_max_filesize 8M’ (without the quotes). However, it is very likely that your system administrator has blocked these values from being changed via .htaccess files. In that case, try asking your system administrator to reach the value for the settings to a properly high number.

If – for whatever reason – these values can’t be changed, there is another route you might try in order to get the template uploaded. By using your FTP login, you can upload the template archive file to the /tmp folder of your server. After doing so, you can use the ‘Install from Directory’ option discussed earlier to install the template on your server. You might need to use the ‘Discover’ feature (found in the ‘Extensions Manager’) to get the template installed fully.

Problem: The template I just installed doesn’t show up in ‘Template Styles’

If no template styles are shown after successfully installing a template, or you’re facing the notice ‘There are no styles installed matching your query’, the template probably hasn’t installed fully yet. There could be a range of issues that are causing this problem, most of which are discussed in this blog on the subject. In most cases doing a ‘Discover’ (found in the ‘Extensions Manager’) will resolve this issue.

Problem: Error “There is already a template using the named directory: _____. are you trying to install the same template again?”

The first thing you should check when you face this issue is whether or not the template you’re installing was intended for the version of Joomla you’re using. For example, if you’re trying to install a Joomla 1.5 template on a Joomla 3 installation, this won’t work. Another possibility is that the template has been set up in such a way that it doesn’t allow itself to be upgraded. Joomla template developers can choose to allow this via the templateDetails.xml file (found in the template archive). Check the 3rd line for the string ‘method=”upgrade”‘. If it isn’t there, try contacting your template provider about this.

Problem: After installing the template, it only shows a home menu item.

This is not a problem with the template per se. What very likely happened is that the template you’re using has named their module positions differently from the template you were using. Therefore the modules are set to show on module positions that no longer exist in this template. You can view the module positions in the current template by appending ?tp=1 to the current URL (after you’ve enabled this feature by visiting the ‘Options’ of the Template Manager in the Joomla Administrator). Another solution would be to use a so-called Quick Installer that comes with most commercial templates. These quick installers are pre-packaged Joomla installations that have the template already installed and modules set at appropriate positions.

Problem: I can’t install Joomla! 3 templates

First of all, make sure the template is actually compatible with Joomla 3. You can do this by opening the templateDetails.xml file that is included in the template archive file. The first line should indicate that this template was developed for Joomla 3. The 3rd line of that file should read ‘version=”3.0’ (though 2.5 usually works as well for Joomla 3 templates). If the file indeed shows that the template was developed for Joomla 3, check to see if any errors are showing. If none are (even after raising the error reporting level via the Global Configuration), try contacting your template provider about this issue.

What happens after template installation

File structure

To see what changes occur in the file structure after a template installation, we did the following:

  1. Do a new installation of Joomla! 3 on a local system
  2. Don’t import any sample data during installation
  3. Clone the file structure
  4. Install the Avori Joomla! template (or any other template)
  5. Run a ‘diff’ command on the pre-template and post-template folders
  • A new folder appeared in the /templates folder, named ‘avori’
  • A new .ini file appeared in the /languages folder.


To see what changes occur in the database after a template installation, we did the following:

  1. Do a new installation of Joomla! 3 on a local system
  2. Don’t import any sample data during installation
  3. Clone the database output
  4. Install the Avori Joomla! template (or any other template)
  5. Run a ‘diff’ command on the pre-template and post-template database output
  • A new row appeared in the #__extensions table
  • A new row appeared in the #__template_styles table.

Template still won’t install?

If none of the solutions above resolve your issue, you can always try to visit the Joomla forum. When asking your question, try to give as many details as possible. Perhaps refer to this post to indicate what you have already tried to resolve the issue and of course don’t forget to use the ‘Forum Assistant‘ before posting your message.

Comments are currently closed.