Title: Configuration file for a VIP Local Development Environment Author: WordPress VIP Documentation Published: August 3, 2023 Last modified: January 22, 2026 --- 1. [VIP Local Development Environment](https://docs.wpvip.com/vip-local-development-environment/) 2. Configuration file for a VIP Local Development Environment # Configuration file for a VIP Local Development Environment A custom configuration file enables a VIP Local Development Environment with specific settings to be created in a repeatable manner. If the configuration file is committed to an application’s source-controlled GitHub repository, multiple team members with access to that repository can use the file to create VIP Local Development Environments with identical settings. **Prerequisites** A user should have the ability to confidently create and customize a VIP Local Development Environment by passing options and values in the `vip dev-env create` and `[vip dev-env update](https://docs.wpvip.com/vip-cli/commands/dev-env/update/)` VIP-CLI commands before attempting to create a local environment with the configuration file method. On the user’s local machine: * [VIP-CLI is installed](https://docs.wpvip.com/vip-cli/installing-vip-cli/) and is updated to [the most current version](https://www.npmjs.com/package/@automattic/vip/v/latest). * [An application’s GitHub repository](https://docs.wpvip.com/github-repository/) has been `git`-cloned to the user’s local machine. ## Create a configuration file In the GitHub repository that has been `git`-cloned to the user’s local machine: 1. Create a `.wpvip` directory in the root of the repository if one does not yet exist. 2. In the `.wpvip` directory, create either a YML file named `vip-dev-env.yml` or an EJS file named `vip-dev-env.yml.ejs`. For example, if an application repository named “example-repo” was cloned to a user’s desktop, the absolute path for the YML configuration file would be similar to: `/ Users/username/Desktop/example-repo/.wpvip/vip-dev-env.yml` ### Minimum requirement At minimum, for a configuration file to be valid for the creation of a VIP Local Development Environment, it must define values for the options `configuration-version` and `slug`. In this example, the configuration file is populated with the minimum required options` configuration-version` defined as `1` (no other value is accepted) and `slug` defined as `example-site`: .wpvip/vip-dev-env.yml ```lang-yml configuration-version: 1 slug: example-site ``` Because `--slug` is defined in a configuration file, all `vip dev-env` commands that are run from within the root of a repository that contains `.wpvip/vip-dev- env.yml` will automatically target the environment created with that configuration file without passing the `--slug` option and its value. ### Add options and values All of the options that can be set in [the VIP-CLI command `vip dev-env create`](https://docs.wpvip.com/vip-cli/commands/dev-env/create/) can also be set in the configuration file. This example demonstrates multiple options and their values set in the configuration file: .wpvip/vip-dev-env.yml ```lang-yml configuration-version: 1 slug: example-site title: Local Example Site multisite: false php: 8.2 wordpress: 6.7 mu-plugins: demo app-code: demo media-redirect-domain: www.example.com elasticsearch: true phpmyadmin: false mailpit: false xdebug: false photon: false cron: true ``` ### Options that are not defined in the configuration file During the creation or update of a local environment, the setup wizard will prompt for any options that are either not defined in the configuration file or are defined with invalid values. In this example output, the setup wizard prompts for a version of PHP when a local environment is created with a configuration file that does not define `php`: ```lang-shell $ vip dev-env create Using environment example-site from /Users/username/Desktop/example-repo/.wpvip/vip-dev-env.yml ? PHP version to use … ❯ 8.2 (recommended) 8.1 8.3 8.4 (experimental) ``` Any options that are not defined in the configuration file can also be set in the initial `vip dev-env create` VIP-CLI command. In this example, the PHP version is set to 8.2 by passing `--php=8.2` in the `vip dev-env create` command: ```lang-shell $ vip dev-env create --php=8.2 Using environment example-site from /Users/example-user/Desktop/example-repo/.wpvip/vip-dev-env.yml SLUG example-site LOCATION /Users/example-user/.local/share/vip/dev-environment/example-site SERVICES nginx, php, database, memcached, elasticsearch, wordpress, vip-mu-plugins NGINX URLS http://example-site.vipdev.lndo.site/ https://example-site.vipdev.lndo.site/ STATUS DOWN LOGIN URL http://example-site.vipdev.lndo.site/wp-admin/?vip-dev-autologin=8bbc27e6-6cd9-4809-9b52-e2cb95b51700 DEFAULT USERNAME vipgo DEFAULT PASSWORD example-password DOCUMENTATION https://docs.wpvip.com/vip-local-development-environment/ ✓ environment created. To start the environment run: vip dev-env start ``` To interact with the environment, it must first be brought into a running state with `vip dev-env start`. ## Apply a configuration file to a local environment A relationship to an existing configuration file can be established with a local environment at the time it is created with the `vip dev-env create` VIP-CLI command. The command that creates the new environment must be run from within a directory where the configuration file has the relative path `.wpvip/vip-dev-env.yml`. This is typically the root of the locally `git`-cloned application repository. If the command `vip dev-env create` is run from the correct location, the output will confirm that the local environment has successfully been created based on the configuration file. In this example, the output message `Using environment example-site from /Users/ username/Desktop/example-repo/.wpvip/vip-dev-env.yml` confirms that the new environment has been created based on the configuration file: ```lang-shell $ vip dev-env create Using environment example-site from /Users/username/Desktop/example-repo/.wpvip/vip-dev-env.yml SLUG example-site LOCATION /Users/username/.local/share/vip/dev-environment/example-site SERVICES nginx, php, database, memcached, elasticsearch, wordpress, vip-mu-plugins NGINX URLS http://example-site.vipdev.lndo.site/ https://example-site.vipdev.lndo.site/ STATUS DOWN LOGIN URL http://example-site.vipdev.lndo.site/wp-admin/?vip-dev-autologin=3e952c17-8402-4753-b5e0-d7ec4710fa09 DEFAULT USERNAME vipgo DEFAULT PASSWORD example-password DOCUMENTATION https://docs.wpvip.com/vip-local-development-environment/ ✓ environment created. To start the environment run: vip dev-env start ``` ### Apply a configuration file to an existing environment A relationship with a configuration file can be created with a local environment that already exists if: * The value of `slug` in the configuration file is updated to match the slug of the existing environment * The command `vip dev-env update` is run from within a directory where the updated configuration file has the relative path `.wpvip/vip-dev-env.yml`. This example output demonstrates the results of the `vip dev-env update` command after a configuration file was modified to associate with an existing local environment with the assigned slug `vip-local`: ```lang-shell $ vip dev-env update Using environment vip-local from /Users/example-user/Desktop/example-repo/.wpvip/vip-dev-env.yml Backup of .lando.yml was created in /Users/example-user/.local/share/vip/dev-environment/vip-local/.lando.backup.yml ✓ environment updated. Please start environment again for changes to take effect: vip dev-env --slug vip-local start ``` For the settings in the configuration file to have an effect, the running environment must be restarted with `vip dev-env start`. ## Update the configuration file Once a local environment has been created with a configuration file, edits can be made to the options and values in the configuration file at any time. For the configuration file update to take effect on the local environment: 1. Save the configuration file in its updated state. 2. Run the command `[vip dev-env update](https://docs.wpvip.com/vip-cli/commands/dev-env/update/)`. 3. Run the command `vip dev-env start`. ## Override an option with a VIP-CLI command Any option set in a configuration file—except for `slug`—can be temporarily overridden by passing a new value for that option in a `vip dev-env update` VIP-CLI command. For example, to override the PHP version that is set to `php: 8.1` in a configuration file: 1. Set the PHP version to 8.2 with the command `vip dev-env update --php=8.2`. 2. Restart the environment with the command `vip dev-env start`. The local environment will run PHP version 8.2 until the override is disabled. ### To disable the override To remove an override and update the local environment to fall back to the configuration file for all options: 1. Run the command `vip dev-env update`. 2. Restart the environment with the command `vip dev-env start`. ## Advanced overrides Settings can also be added to the configuration file to automatically generate a custom `.lando.local.yml` for a local environment. Below the standard options in a configuration file, add an `overrides:` section where custom settings for `services` and `tooling` can be defined. Settings that are defined in the `overrides:` section of a configuration file will be copied into  `.lando.local.yml` for the local environment that is created with that configuration file. [An example of these settings](https://github.com/Automattic/vip-integrations-starter-kit/blob/main/.wpvip/vip-dev-env.yml.ejs) can be reviewed in the VIP Integrations Starter Kit. Edits can be made to the configuration file at any time, but for the changes to take effect the local environment must be updated (i.e. `vip dev-env update`) and restarted (i.e. `vip dev-env start`). Last updated: January 22, 2026