Learn Build5Nines Forum

Find answers, ask questions, and connect with our
global community of IT professionals.

Forums HashiCorp Terraform Should .terraform.lock.hcl be included in the .gitignore file?

  • Should .terraform.lock.hcl be included in the .gitignore file?

    Posted by Joshua Falken on June 28, 2023 at 1:43 pm

    From my current knowledge, there is no reason .terraform.lock.hcl should be included in the .gitignore. Nothing about this file is private, right?

    Joshua Falken replied 3 months, 1 week ago 1 Member · 1 Reply
  • 1 Reply
  • Joshua Falken

    June 28, 2023 at 1:43 pm

    Per the Terraform documentation on the Dependency Lock File:

    Terraform automatically creates or updates the dependency lock file each time you run the terraform init command. You should include this file in your version control repository so that you can discuss potential changes to your external dependencies via code review, just as you would discuss potential changes to your configuration itself.

    The key to understanding why you should commit that file is found in the following section on Dependency Installation Behavior:

    When terraform init is working on installing all of the providers needed for a configuration, Terraform considers both the version constraints in the configuration and the version selections recorded in the lock file.

    If a particular provider has no existing recorded selection, Terraform will select the newest available version that matches the given version constraint, and then update the lock file to include that selection.

    If a particular provider already has a selection recorded in the lock file, Terraform will always re-select that version for installation, even if a newer version has become available. You can override that behavior by adding the -upgrade option when you run terraform init, in which case Terraform will disregard the existing selections and once again select the newest available version matching the version constraint.

    Essentially this is intended to have Terraform continue to use the version of the provider selected when you added it. If you do not checkin the lock file, you will always be automatically upgraded to the latest version that obeys the constraint in code, which could lead to unintended consequences.

    Note: You can force Terraform to upgrade when doing the init call by passing the -upgrade flag.

    terraform init -upgrade

    Update for Cross-Platform Development

    From the Terraform documentation on the providers lock command:

    Specifying Target Platforms In your environment you may, for example, have both developers who work with your Terraform configuration on their Windows or macOS workstations and automated systems that apply the configuration while running on Linux.

    In that situation, you could choose to verify that all of your providers support all of those platforms, and to pre-populate the lock file with the necessary checksums, by running terraform providers lock and specifying those three platforms:

    terraform providers lock \
        -platform=windows_amd64 \
        -platform=darwin_amd64 \
        -platform=linux_amd64 \
        -platform=darwin_arm64 \

    The above example uses Unix-style shell wrapping syntax for readability. If you are running the command on Windows then you will need to replace the backslashes with carets (for cmd) or backticks (for PowerShell).

    So you should still check the lock file into version control, but you should ensure the lock file contains the checksums for providers on all platforms.