opentf/website/docs/cli/commands/init.mdx

---
description: >-
  The tofu init command initializes a working directory containing
  configuration files and installs plugins for required providers.
---

# Command: init

The `tofu init` command initializes a working directory
containing OpenTofu configuration files. This is the first command that should
be run after writing a new OpenTofu configuration or cloning an existing one
from version control. It is safe to run this command multiple times.

## Usage

Usage: `tofu init [options]`

This command performs several different initialization steps in order to
prepare the current working directory for use with OpenTofu. More details on
these are in the sections below, but in most cases it is not necessary to worry
about these individual steps.

This command is always safe to run multiple times, to bring the working
directory up to date with changes in the configuration. Though subsequent runs
may give errors, this command will never delete your existing configuration or
state.

This command requires value assignment for variables used in [module sources](../../language/modules/sources.mdx#support-for-variable-and-local-evaluation)
and [backend configuration](../../language/settings/backends/configuration.mdx#variables-and-locals)
blocks. Refer to [Assigning Values to Root Module Variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables)
for more information.

## General Options

The following options apply to all of (or several of) the initialization steps:

* `-input=true` Ask for input if necessary. If false, will error if
  input was required.

* `-lock=false` Disable locking of state files during state-related operations.

* `-lock-timeout=<duration>` Override the time OpenTofu will wait to acquire
  a state lock. The default is `0s` (zero seconds), which causes immediate
  failure if the lock is already held by another process.

* `-no-color` Disable color codes in the command output.

* `-upgrade` Opt to upgrade modules and plugins as part of their respective
  installation steps. See the sections below for more details.

* `-json` Produce output in a machine-readable JSON format, suitable for use
  in text editor integrations and other automated systems. Always disables color.

* `-var 'NAME=VALUE'` - Sets a value for a single
  [input variable](../../language/values/variables.mdx) declared in the
  root module of the configuration. Use this option multiple times to set
  more than one variable. Refer to
  [Input Variables on the Command Line](plan.mdx#input-variables-on-the-command-line) for more information.

* `-var-file=FILENAME` - Sets values for potentially many
  [input variables](../../language/values/variables.mdx) declared in the
  root module of the configuration, using definitions from a
  ["tfvars" file](../../language/values/variables.mdx#variable-definitions-tfvars-files).
  Use this option multiple times to include values from more than one file.

There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.

## Copy a Source Module

By default, `tofu init` assumes that the working directory already
contains a configuration and will attempt to initialize that configuration.

Optionally, init can be run against an empty directory with the
`-from-module=MODULE-SOURCE` option, in which case the given module will be
copied into the target directory before any other initialization steps are
run.

This special mode of operation supports two use-cases:

* Given a version control source, it can serve as a shorthand for checking out
  a configuration from version control and then initializing the working directory
  for it.

* If the source refers to an _example_ configuration, it can be copied into
  a local directory to be used as a basis for a new configuration.

For routine use it is recommended to check out configuration from version
control separately, using the version control system's own commands. This way
it is possible to pass extra flags to the version control system when necessary,
and to perform other preparation steps (such as configuration generation, or
activating credentials) before running `tofu init`.

## Backend Initialization

During init, the root configuration directory is consulted for
[backend configuration](../../language/settings/backends/configuration.mdx) and the chosen backend
is initialized using the given configuration settings.

:::note
Use of [variables in the backend configuration](../../language/settings/backends/configuration.mdx#variables-and-locals)
block requires [assigning values to root module variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu init`.
:::

Re-running init with an already-initialized backend will update the working
directory to use the new backend settings. Either `-reconfigure` or
`-migrate-state` must be supplied to update the backend configuration.

The `-migrate-state` option will attempt to copy existing state to the new
backend, and depending on what changed, may result in interactive prompts to
confirm migration of workspace states.  The `-force-copy` option suppresses
these prompts and answers "yes" to the migration questions.
Enabling `-force-copy` also automatically enables the `-migrate-state` option.

The `-reconfigure` option disregards any existing configuration, preventing
migration of any existing state.

To skip backend configuration, use `-backend=false`. Note that some other init
steps require an initialized backend, so it is recommended to use this flag only
when the working directory was already previously initialized for a particular
backend.

The `-backend-config=...` option can be used for
[partial backend configuration](../../language/settings/backends/configuration.mdx#partial-configuration),
in situations where the backend settings are dynamic or sensitive and so cannot
be statically specified in the configuration file.

## Child Module Installation

During init, the configuration is searched for `module` blocks, and the source
code for referenced [modules](../../language/modules/develop/index.mdx) is retrieved from the locations
given in their `source` arguments.

Re-running init with modules already installed will install the sources for
any modules that were added to configuration since the last init, but will not
change any already-installed modules. Use `-upgrade` to override this behavior,
updating all modules to the latest available source code.

To skip child module installation, use `-get=false`. Note that some other init
steps can complete only when the module tree is complete, so it's recommended
to use this flag only when the working directory was already previously
initialized with its child modules.

## Plugin Installation

Most OpenTofu providers are published separately from OpenTofu as plugins.
During init, OpenTofu searches the configuration for both direct and indirect
references to providers and attempts to install the plugins for those providers.

For providers that are published in either
[the public OpenTofu Registry](https://registry.opentofu.org/) or in a
third-party provider registry, `tofu init` will automatically find,
download, and install the necessary provider plugins. If you cannot or do not
wish to install providers from their origin registries, you can customize how
OpenTofu installs providers using
[the provider installation settings in the CLI configuration](../../cli/config/config-file.mdx#provider-installation).

For more information about specifying which providers are required for each
of your modules, see [Provider Requirements](../../language/providers/requirements.mdx).

After successful installation, OpenTofu writes information about the selected
providers to [the dependency lock file](../../language/files/dependency-lock.mdx).
You should commit this file to your version control system to ensure that
when you run `tofu init` again in future OpenTofu will select exactly
the same provider versions. Use the `-upgrade` option if you want OpenTofu
to ignore the dependency lock file and consider installing newer versions.

You can modify `tofu init`'s plugin behavior with the following options:

* `-upgrade` Upgrade all previously-selected plugins to the newest version
  that complies with the configuration's version constraints. This will
  cause OpenTofu to ignore any selections recorded in the dependency lock
  file, and to take the newest available version matching the configured
  version constraints.
* `-plugin-dir=PATH` — Force plugin installation to read plugins _only_ from
  the specified directory, as if it had been configured as a `filesystem_mirror`
  in the CLI configuration. If you intend to routinely use a particular
  filesystem mirror then we recommend
  [configuring OpenTofu's installation methods globally](../../cli/config/config-file.mdx#provider-installation).
  You can use `-plugin-dir` as a one-time override for exceptional situations,
  such as if you are testing a local build of a provider plugin you are
  currently developing.
* `-lockfile=MODE` Set a dependency lockfile mode.

The valid values for the lockfile mode are as follows:

* `readonly`: suppress the lockfile changes, but verify checksums against the
  information already recorded. It conflicts with the `-upgrade` flag. If you
  update the lockfile with third-party dependency management tools, it would be
  useful to control when it changes explicitly.

## Running `tofu init` in automation

For teams that use OpenTofu as a key part of a change management and
deployment pipeline, it can be desirable to orchestrate OpenTofu runs in some
sort of automation in order to ensure consistency between runs, and provide
other interesting features such as integration with version control hooks.

There are some special concerns when running `init` in such an environment,
including optionally making plugins available locally to avoid repeated
re-installation.

## Passing a Different Configuration Directory

If your workflow relies on overriding
the root module directory, use
[the `-chdir` global option](../../cli/commands/index.mdx#switching-working-directory-with-chdir)
instead, which works across all commands and makes OpenTofu consistently look
in the given directory for all files it would normally read or write in the
current working directory.