--- page_title: Override Files - Configuration Language description: >- Override files merge additional settings into existing configuration objects. Learn how to use override files and about merging behavior. --- # Override Files Terraform normally loads all of the `.tf` and `.tf.json` files within a directory and expects each one to define a distinct set of configuration objects. If two files attempt to define the same object, Terraform returns an error. In some rare cases, it is convenient to be able to override specific portions of an existing configuration object in a separate file. For example, a human-edited configuration file in the Terraform language native syntax could be partially overridden using a programmatically-generated file in JSON syntax. For these rare situations, Terraform has special handling of any configuration file whose name ends in `_override.tf` or `_override.tf.json`. This special handling also applies to a file named literally `override.tf` or `override.tf.json`. Terraform initially skips these _override files_ when loading configuration, and then afterwards processes each one in turn (in lexicographical order). For each top-level block defined in an override file, Terraform attempts to find an already-defined object corresponding to that block and then merges the override block contents into the existing object. Use override files only in special circumstances. Over-use of override files hurts readability, since a reader looking only at the original files cannot easily see that some portions of those files have been overridden without consulting all of the override files that are present. When using override files, use comments in the original files to warn future readers about which override files apply changes to each block. ## Example If you have a Terraform configuration `example.tf` with the following contents: ```hcl resource "aws_instance" "web" { instance_type = "t2.micro" ami = "ami-408c7f28" } ``` ...and you created a file `override.tf` containing the following: ```hcl resource "aws_instance" "web" { ami = "foo" } ``` Terraform will merge the latter into the former, behaving as if the original configuration had been as follows: ```hcl resource "aws_instance" "web" { instance_type = "t2.micro" ami = "foo" } ``` ## Merging Behavior The merging behavior is slightly different for each block type, and some special constructs within certain blocks are merged in a special way. The general rule, which applies in most cases, is: * A top-level block in an override file merges with a block in a normal configuration file that has the same block header. The block _header_ is the block type and any quoted labels that follow it. * Within a top-level block, an attribute argument within an override block replaces any argument of the same name in the original block. * Within a top-level block, any nested blocks within an override block replace _all_ blocks of the same type in the original block. Any block types that do not appear in the override block remain from the original block. * The contents of nested configuration blocks are not merged. * The resulting _merged block_ must still comply with any validation rules that apply to the given block type. If more than one override file defines the same top-level block, the overriding effect is compounded, with later blocks taking precedence over earlier blocks. Overrides are processed in order first by filename (in lexicographical order) and then by position in each file. The following sections describe the special merging behaviors that apply to specific arguments within certain top-level block types. ### Merging `resource` and `data` blocks Within a `resource` block, the contents of any `lifecycle` nested block are merged on an argument-by-argument basis. For example, if an override block sets only the `create_before_destroy` argument then any `ignore_changes` argument in the original block will be preserved. If an overriding `resource` block contains one or more `provisioner` blocks then any `provisioner` blocks in the original block are ignored. If an overriding `resource` block contains a `connection` block then it completely overrides any `connection` block present in the original block. The `depends_on` meta-argument may not be used in override blocks, and will produce an error. ### Merging `variable` blocks The arguments within a `variable` block are merged in the standard way described above, but some special considerations apply due to the interactions between the `type` and `default` arguments. If the original block defines a `default` value and an override block changes the variable's `type`, Terraform attempts to convert the default value to the overridden type, producing an error if this conversion is not possible. Conversely, if the original block defines a `type` and an override block changes the `default`, the overridden default value must be compatible with the original type specification. ### Merging `output` blocks The `depends_on` meta-argument may not be used in override blocks, and will produce an error. ### Merging `locals` blocks Each `locals` block defines a number of named values. Overrides are applied on a value-by-value basis, ignoring which `locals` block they are defined in. ### Merging `terraform` blocks The settings within `terraform` blocks are considered individually when merging. If the `required_providers` argument is set, its value is merged on an element-by-element basis, which allows an override block to adjust the constraint for a single provider without affecting the constraints for other providers. In both the `required_version` and `required_providers` settings, each override constraint entirely replaces the constraints for the same component in the original block. If both the base block and the override block both set `required_version` then the constraints in the base block are entirely ignored. The presence of a block defining a backend (either `cloud` or `backend`) in an override file always takes precedence over a block defining a backend in the original configuration. That is, if a `cloud` block is set within the original configuration and a `backend` block is set in the override file, Terraform will use the `backend` block specified in the override file upon merging. Similarly, if a `backend` block is set within the original configuration and a `cloud` block is set in the override file, Terraform will use the `cloud` block specified in the override file upon merging.