Some Sitecore documentation I found says..

Do not make changes directly to the configuration files. Instead, you must create a patch file that performs the required changes during run time.

But it doesn't explain why you should do this. What's the problem with changing the config files directly?

3 Answers 3


It is not recommended to update directly Sitecore files because you will have problems on updating Sitecore and is really difficult to know what exactly you changed.

Since Sitecore runs within IIS, it is natural for Sitecore to be configured using IIS’s configuration file, Web.config. The path to Sitecore-specific settings is /configuration/sitecore.

Sitecore supports distributed configuration. This means that Sitecore-specific settings (those settings located under /configuration/sitecore) can be spread out between multiple files. The process Sitecore uses to merge multiple config files is called called “config patching”.

How Patching Works

Sitecore uses a custom configuration section handler to merge patch files. The handler finds files with the .config extension in the /App_Config/Include folder and combines the files it finds with Web.config. The combined configuration is used at runtime.

Patch File Names

Patch files are merged with Web.config in alphabetical order. This means configuration in a patch file named a.config will appear before configuration in a patch file named b.config.

When the same configuration is found in multiple patch files, the configuration from the last patch file processed is the configuration that is used.

Patch File Folders

Subfolders of /App_Config/Include are processed after files in the /App_Config/Includefolder. Folders are processed in alphabetical order, as are the files in each folder.

For example, if the same configuration is defined in the following files the configuration from the last file listed is used:

/App_Config/Include/z.config /App_Config/Include/b/b.config /App_Config/Include/b/c.config /App_Config/Include/c/a.config [used]


Patching only works on the Sitecore configuration section. This is located in Web.config under /configuration/sitecore. Configuration in other sections of Web.config cannot be controlled through patching.

How to See the Result of Patching

Since the Sitecore configuration is the result of the merging of configuration from Web.config with a variable number of patch files, you cannot look at Web.config or any individual patch file in order to determine the configuration Sitecore is using. Sitecore includes an admin script to do this.

The script displays the results of the config file patching process.


More information can be found here:

http://sitecore-community.github.io/docs/documentation/Sitecore%20Fundamentals/Patch%20Files/ https://doc.sitecore.com/developers/90/platform-administration-and-architecture/en/use-a-patch-file-to-customize-the-sitecore-configuration.html

Update :

Starting from Sitecore 9 we have OOTB configuration layers. Using Configuration Layers/Roles You don't need a patch for your patch on different roles (CM,CD, Proc, Rep, etc) Just deploy everything and set the server role.

Sitecore divides configuration files into layers. Each layer consists of a dedicated folder under the App_config folder. By default, there are four layers:

  • Sitecore
  • Modules
  • Custom
  • Environment

Each layer influences a specific area of Sitecore functionality.

Sitecore divides the configuration files into layers in order to:

Give you better control over when Sitecore loads files at runtime.

Allow you to disable all configuration files in a layer at once.

More informations can be found here: https://doc.sitecore.com/developers/90/platform-administration-and-architecture/en/configuration-layers.html


If your Sitecore solution is 8.1 Update 3 or Sitecore 8.2 you can install a Sitecore Configuration Roles module .https://github.com/Sitecore/Sitecore-Configuration-Roles

  • 1
    Vlad.. good answer, but so Sitecore 8-ish :) In v9 we have layers.config to order the patch file order.. you might want to add that.
    – Gatogordo
    Dec 18, 2018 at 7:31
  • :) I forgot about layers config Dec 18, 2018 at 7:32

There are no issues to change the Sitecore Configuration file directly. However, changing Sitecore configuration directly can cause issues later when you upgrade your Sitecore instances. This is because when you upgrade Sitecore, it will override the configuration files.

Moreover, based on personal experience, when you touch the Sitecore configuration file directly, it is difficult to know later whether this is a default value from Sitecore or it is a custom value. You'll need to compare the files with a vanilla Sitecore instance.


In my opinion, the most important reason is upgrading to newer version of Sitecore.

Let's imagine 2 scenarios:

  1. You made changes in Sitecore config files directly.

You're upgrading and now you have to check every single Sitecore config file, find the differences with the original and apply the same in new version.

  1. You used patch files only.

You're upgrading and you know you can remove all the Sitecore configs from the older version and add config from the newer version and your patches will still be there.

In both cases you need to check if patch is still needed, relevant and even if it's working, but that's another thing.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.