A Guided Tour of Joomla's configuration.php File

A Guided Tour of Joomla's configuration.php File

Joomlashack members often ask us to help with problems with paths, passwords, data base connections and other basic configuration issues. This is especially true after a migration or move of a site.

Most of the fixes for these problems can be made in your configuration.php file. We're going to help you get to know it this very important file.

In this guide, were going to tell you:

  • Where you can locate your configuration.php file.
  • What each line affects and common settings.

This is not a comprehensive coding guide, but is a general reference to help you understand this important Joomla file.

Location of the configuration.php file


Here's a picture of the location using Filezilla. This installation is in a sub directory called "joomla" .

Your configuration.php file is located in the root of your joomla installation. If it's in the main directory the path to it would look something like this:

  • /home/username/public_html/configuration.php

In a sub directory or sub domain:

  • /home/username/public_html/subdirectory/configuration.php

On your computer (using XAMPP as an example)

  • C:\Documents and Settings\Ed\My Documents\xampp\htdocs\J17\configuration.php

I shouldn't have to say this, but I will. Make a backup of your current file before you do anything to it. Use a test site or play with it in a text editor offline for practice. Don't make changes without a backup. Make a backup before you move a file to a different server or directory.

We'll go through the file line-by-line and create a quick reference for each line, with some notes where further explanation might be needed.

Site Settings

  • $offline : When set to "0" the site is online. Set to "1" the site is offline
  • $offline_message : You can write any text message on this line.
  • $sitename : The name of the site as it appears in headings
  • $editor : The editor that is chosen as default in global configuration
  • $list_limit :The length of lists in the Control Panel for all Users. By default, this is set to 20.
  • $access : The default access level to the site. "1" is public access; "2" is registered; "3" is special

Debug Settings

  • $debug : "0" is off. "1" is on.
  • $debug_lang : "0" is off. "1" is on.


  • $debug : This will turn on the debugging system of Joomla!. When set to Yes, this tool will provide diagnostic information, language translations, and SQL errors. If any such issues or errors occur, they will be displayed at the bottom of each page, in both the front-end and back-end.
  • $debug_lang : This will turn on the debugging indicators (*...*) or (?...?) for the Joomla! Language files. Debug Language will work without the Debug System tool set to on. But it will not provide additional detailed references which would help in correcting any errors.

Database Settings

  • $dbtype : "mysqli" or "mysql"
  • $host : "localhost" on many servers, not all.
  • $user : The name of the data base user that has access to the data base.
  • $password : The password associated with the data base user. Not your admin password or FTP password.
  • $db : The data base name created when you created the data base.
  • $dbprefix : At least three characters ending in an underscore. (Set when you installed joomla)


You need this information when you install the site. Forgetting to change this is often the cause of problems when moving a site. Before moving any site, make a backup copy of configuration.php so you can refer to the original settings if you need them.

  • $dbtype : only change this if you have changed servers and using a different type.
  • $host : most servers this is localhost. Godaddy and a some others have different names. Check with your hosting company if you're not sure.
  • $user : On shared cPanel servers it is often prefixed with the user name - for example edandrea_ed. On your local machine there will not be a prefix unless you created one. It shouldn't be root in any case. If you create a site on your local server and don't specify password when you create a data base, you will be able to access the data without a password. This is not secure when you move to web server online.
  • $db : On shared cPanel servers this is usually prefixed with a username - for example edandrea_jml1. On your local machine there will not be a prefix unless you created one. On Godaddy servers this name is generated by their service and you will not be able to create your own, see their documentation if you need it.
  • $dbprefix : You cannot create a new one here. This must be the one that was used when the data base was created, or that is actually used by the database. If you have more than one data base prefix, you can change this, but you can't create a new one. 

Assorted extra features

  • $live_site : The actual URL of the site for example - https://yourdomain.com (unless your site is in a subdirectory)
  • $secret: : DO NOT CHANGE
  • $gzip : "0" is off; "1" is on.
  • $error_reporting : "-1" is the appropriate level.
  • $helpurl : default is joomla help. Can be set to your own help pages.


  • $live_site : In the newest versions this should not have a value. There may be times you do need to fill in a value. If you are redirecting a url you need to put the actual url to the live site on this line. Or if you are creating a copy of a site for testing and modification. For example, I have a test site at https://dashhelp.com/joomla17 which is a copy of my main site. had to change this to line in the configuratiion.php file on the copy. You will get a page not found error if this is not set to 'https://yourdomain.com/directory" or in the case of a subdomain "https://subdomain.yourdomain.com" Joomla uses this url to create relative paths. Essential to check this on test sites.
  • $secret : This is generated when Joomla! is first installed and is not changeable. It is used internally by Joomla! for security purposes.
  • $error_reporting : This sets the appropriate level of reporting. The default setting is System Default. Errors can occur that don't have any effect on the site. You don't need to log all errors unless you're doing some detailed debugging work. Your logs will just eat up your disk space otherwise.
  • $helpurl : The place Joomla! looks for help information when you click the Help button (visible in many screens and options of the administration panel). By default, it uses Joomla!'s main help site, but you could create your own help site, or link people to your ticket system for help.
  • $ftp_host: : "" is the default IP for localhost. Your server may be different.
    $ftp_port : "21" is normal default. Check with your host if you are having problems. Not all servers are the same.
    $ftp_user : your FTP user name
    $ftp_pass : your FTP password
    $ftp_root: : usually a path like /home/username/public_html (no trailing slash)
    $ftp_enable : This setting tells Joomla! to use it's built-in FTP function instead of the process used by PHP.

Time Zone Settings

  • $offset : default is UTC
    $offset_user : default is UTC


$offset. This tool sets the current date and time. The set time should be where the site's server is located. The default setting is (UTC 00:00) Western Europe Time, London, Lisbon, Casablanca. Here's an example of the offset if the server is in California - US Pacific time $offset = 'America/Los_Angeles';

Email Settings

  • $mailer : "mail" uses the PHP mail function; "sendmail" uses SMTP mail on the server.
  • $mailfrom : From E-mail. The email address used by Joomla! to send site email.
  • $sendmail : The path where the Sendmail program is located. This path is only used if Mailer is set to Sendmail.
  • $smtpauth : If the SMTP server requires authentication to send mail, set this to Yes. Otherwise leave it at No. This is only used if Mailer is set to Sendmail.
  • $smtpuser : The username to use for access to the SMTP host. This is only used if Mailer is set to Sendmail.
  • $smtppass: The password to use for access to the SMTP host. This is only used if Mailer is set to Sendmail.
  • $smtphost : SMTP Host. The SMTP address to use when sending mail. This is only used if Mailer is set to Sendmail.
  • $smtpsecure : Select the security model your SMTP server uses - Default is None. Options are SSL and TTL.
  • $smtpport : SMTP Port. Most unsecured servers use port 25 and most secure servers use port 465. Check with your host.

Log Settings

  • $log_path : '//home/username/public_html/j/logs';
    $tmp_path : :'//home/username\public_html/tmp';


  • $log_path : The path where the logs should be stored. The Joomla! installer should automatically fill in this folder. It's not critical to the operation of the site, so if it's wrong you will only know it if you try to check the logs.
  • $tmp_path : This is an important setting and should be filled in properly. Many problems found when moving sites are caused because joomla is looking for the old tmp folder. If you get any errors regarding the tmp folder check this path and make sure it's correct..

Cache Settings

  • $caching : "0" is off; "1" Conservative setting; "2" Progressive Setting
    $cache_handler : "file" full cacheing ; "cachelite" lite cacheing


  • $caching : This setting sets the maximum length of time (in minutes) for a cache file to be stored before it is refreshed. The default setting is 15 minutes.
  • $cache_handler : This setting sets how the cache operates. There is only one caching mechanism which is file-based.
    Cachelite is an alternative to full caching.

Metadata Settings

  • $MetaDesc : Create a text description for SEO.
    $MetaKeys : Insert keywords separated by a comma.
    $MetaAuthor : "0" is no; "1" is yes.


  • $MetaDesc : This is the Site Meta Description. This is the description of the site which is indexed by search engine spiders.
  • $MetaKeys : These are Site Meta Keywords. These keywords describe the site and are the basis for improving the ability of search engine spiders ability to index the site.
  • $MetaAuthor : This shows Author Meta Tag. It shows the Author Meta information for articles and is used by search engine spiders when indexing the site.

SEO Settings (Search Engine Optimization)

  • $sef : "0: is no; "1" is yes
    $sef_rewrite : "0" is no; "1" is yes
    $sef_suffix : "0" is no; "1" is yes
    $unicodeslugs : "0" is no; "1" is yes
    $feed_limit : default is 10 - any integer can be used


  • $sef : This controls Search Engine Friendly URLs. When set to Yes, URLs are rewritten to be more friendly for search engine spiders. For example, the URL: www.example.com/index.php?option=com_content&view=etc..., would turn into: www.example.com/alias. Most of the items created in Joomla! have an Alias box where a search engine friendly URL can be inserted. The default setting is No.
  • $sef_rewrite : When set to Yes, Joomla! will use the mod_rewrite settings of Apache when creating search engine friendly URLs. Please note: it is advised that you do not modify any .htaccess file without an understanding of how it works. You must use the .htaccess file provided with Joomla! in order to use this setting. To use this file, rename the htaccess.txt file (found in the root directory) to .htaccess. By default, this setting is set to No.
  • $sef_suffix : When set to Yes, Joomla! will add .html to the end of the URLs. The default setting is No.
  • $unicodeslugs : Choose between transliteration and unicode aliases. Transliteration is default. This is an advanced setting and you probably will not need to change this unless you are and SEO expert.

Session Settings

  • $lifetime : a whole number indicating minutes.
    $session_handler : "database" or "none"


  • $lifetime : This setting sets how long a session should last and how long a user can remain signed in for (before logging them off for being inactive). The default setting is 15 minutes.
  • $session_handler : This setting sets how the session should be handled once a user connects and logs into the site. The default setting is set to Database.