Local and WP Engine Connect

Manually setting up a local environment to develop a website can be a needlessly extensive process. Local is a free program that allows you to easily set up a WordPress environment on your local computer, regardless of your skill level or experience. Local is supported on Windows, Mac and Linux systems.

Once a site is created it can then be transferred to any account type or hosting provider, such as WP Engine. Local provides an experience that is user-friendly and speeds up the overall development workflow.


While Local supports multisite, Local Connect currently does not support multisite configurations. For more information about multisite with Local, check here.

Local Features

The following features come standard with Local. We also recommend keeping your eye on the Local Release Notes page for new feature releases.

  • Local development environment
  • Push/pull any environment
  • Demo site URL
  • SSL
  • Mac/Windows/Linux compatibility
  • Sleek GUI (General User Interface)

The best part about Local is that it’s totally free! Check out this article to learn more about how all the Local Pro features have been made free for everyone.

For feature requests and additional questions, please refer to the Local community forums.

Install Local

Before starting the setup process, we recommend signing up for the Local community forums. The WordPress community is always a great source of information, feedback and guidance.

  1. Get the Local application for free, by clicking “Download” here
  2. Choose your platform
  3. Fill in your information
  4. Download and Save the installation package to your computer
  5. Open the installation package for Local on your computer
  6. Follow the installation setup prompts
  7. Launch Local on your computer

Connect Local to WP Engine

The WP Engine Connect feature will allow Local users to connect any Sites they have created on their WP Engine account and download associated environments. Additionally, if a website was initially setup on WP Engine, WP Engine Connect can help pull that site to Local!

Enable API Access

  1. Open the API Access page of your WP Engine User Portal: https://my.wpengine.com/api_access
    • Or, in the User Portal at Users > API access
  2. Locate the account name and toggle Account API Access to Enabled
Screenshot of the API Access page in the WP Engine User Portal showing the toggle button to enable api access for an account


Want to know more about WP Engine’s customer API? See our guide.

Connect Local to WP Engine

  1. Open the Local application on the computer
  2. Click Connect in the menu on the left (cloud icon)
  3. Click Connect to a platform
  1. Next to WP Engine click Log in
  2. You will be prompted to log in to WP Engine using your User Portal credentials
  3. After logging in, you’ll be redirected back to Local.

You’ll know you’ve logged in successfully because your WP Engine sites will now be listed within the “Connect” tab of Local!

Pull to Local From WP Engine

When setting up a site in Local, an initial pull will typically be made from WP Engine to copy content locally. After the initial pull, subsequent pulls can be made any time to overwrite you local content.

Initial Pull to Local

This process needs to take place the very first time you pull to Local from WP Engine.

  1. Ensure you’ve already connected Local to your WP Engine account
  2. Open Local on your computer
  3. Go the Connect tab
  4. Locate a Site in the list
  5. Click PULL TO LOCAL
  6. Choose whether or not to include the database

Initial Partial Pull

If you have a large site or otherwise do not wish to pull all of your website’s content locally, you can perform a partial pull. To do a partial pull from WP Engine to Local:

  1. Ensure you’ve already connected Local to your WP Engine account
  2. Open Local on your computer
  3. Create a blank site in Local by clicking the green plus icon on the lower left
  4. Connect the new blank site to WP Engine by selecting Connected to, then selecting WP Engine
  1. Next, click the cloud icon Pull from WP Engine to initiate Magic Sync.
  1. You will now be presented with the file system, from which you can deselect the content you do not want pulled into Local.
  2. When you’re done selecting assets, click PULL FROM WP ENGINE

Subsequent Pulls to Local

After the initial pull to Local, additional pulls can be made using the following steps.

  1. Open the Local app
  2. Select the Local Sites tab
  3. Select the site name
  4. Click START SITE at the top right
  5. Click PULL TO LOCAL in the lower right
  6. Choose whether or not to include the database

Push to WP Engine from Local

  1. Open Local connected to WP Engine
  2. Click Start Site on the environment that you want to push
  3. Click the bottom right hand icon to push to WP Engine
  1. Choose an environment to push to:
    • Production, Staging and Development are all options if already created in User Portal
    • If an environment doesn’t yet exist, click the link to create one from the User Portal
  2. Chose whether or not to push the database
    • Including the database will overwrite all database information on the destination environment
    • It is never advised to include a database when pushing to Production
  3. A success message will display within Local when the push has completed:
Site Pushed! Your site has been pushed to WP Engine


If you do not wish to push your site to WP Engine, you can take it to another hosting provider and upload it to them as well. Be sure to check with the new host first if they accept Local’s formatting and configurations. You can read more in this community forum thread.

Push or Pull Only Specific Files

In the development process, there may be times when you need to push or pull only specific files. Similar to how Git has a .gitignore file, Local has a set of ignore files for pushing and pulling. You can modify these files if you need to.

The .wpe-pull-ignore and .wpe-push-ignore files can be found in the site root for Local.

MacOS Users

  • /Users/computer-username/Local Sites/SITE-NAME/app/public
  • Example: /Users/larry.frog/Local Sites/jdiazii22/app/public

WindowsOS Users

  • C:/Users/computer-username/Local Sites/SITE-NAME/app/public
  • Example: C:\Users\larry\Local Sites\aceofspades\app\public


  • If the files are missing they will be recreated with default values after the first push/pull.
  • The wp-config.php file is excluded from the push/pull. However, it can still be modified locally, i.e., enabling debug mode, max file size, etc. Any changes made to that file will need to be manually updated after the push/pull.
  • The file will be blank, but in the background, we automatically filter out all of the exclusions noted here.

Backup Process

Like other files on your computer, backing up your Local sites is essential. Local site are stored in ~/Local Sites, and you may be able to recover sites from this directory. Follow the instructions below for a complete backup:

  1. Click Start Site on your Local site to start it
  2. Right-click or CTRL+click on your site
  3. Select Export
    • This will include site files and database in a single .zip archive
  4. Click Export Site
  5. Depending on the size of the site, exports can take several minutes

Success! You now have a backup of your Local Site. Simply drag this .zip archive into Local to import content from the backup.


If you export your site to your computer and also backup your computer (EX: to an external hard drive), you’ll backup your Local Site backup for extra protection!

Migrate DevKit to Local

If you’ve been using DevKit by WP Engine, you will need to migrate your content into Local.

  1. Open terminal on your local machine
  2. Change directory into your site. Replace SITENAME with your own site name.
    • cd SITENAME
  3. Initiate your DevKit environment:
    • wpe start
  4. Once in the running site, run the following command. Replace SITENAME with your own site name in DevKit.
    • mkdir local-SITENAME; wpe wp db export local-SITENAME.sql && mv local-SITENAME.sql local-SITENAME/; rsync -avP wp-content/ local-SITENAME/wp-content --exclude mu-plugins; zip -r local-SITENAME.zip local-SITENAME/
  5. Open the Local app on your computer
  6. Drag and drop the zip file created in step 4 into Local from a finder window.
    • With the above command, your zip will be called local-SITENAME.zip and is stored in the root of your DevKit environment.
  7. The import process will begin in the Local app
  8. Start the site in Local to confirm the import was successful

For additional assistance, please use the community forum.


If you need to migrate from Local by Flywheel (versions up to 3.3) to Local (versions 5.0+), check out this guide from Flywheel.

Manual Import

If the pull from WP Engine fails to import your environment(s), use the following steps to manually import each environment from a backup.

  1. Create a backup of the environment
  2. Download the full backup as a zip
  3. Rename the zip file locally to match the name of your environment
    • EX: mystagingenv.zip
  4. Open Local on your machine
  5. Open the File menu
  6. Select Import Site
  1. Open the file from Step 3
  2. Confirm the Environment name
  3. Click Continue
  4. Select Preferred
  5. Click Import Site

Once the import completes, we recommend clicking View Site at the top right to confirm that it works.

Local Connect Issues

Most issues connecting to WP Engine via Local Connect can be solved by simply logging out and logging back in. This causes new API credentials and a new SSH key to be generated for the account.

To reconnect Local to WP Engine, open the Connect tab within Local to complete the process.

  1. Open Local on your computer
  2. Click the Connect icon in the sidebar
  3. Click My Hosts in the top right
  4. Log out of WP Engine
  5. Click Connect to a platform
  6. Click Log in next to the WP Engine logo
  7. Enter your WP Engine credentials in the browser window
  8. The browser should refocus Local and a list of the available sites will be shown in the app

For general Local troubleshooting, see Troubleshoot: Local.

Local Logging

When troubleshooting an issue Support may request your Local log file. Version 5 of Local introduced a new file called local-lightning.log. Older versions of Local will use a log file called local-by-flywheel.log.

For full documentation on logging, read the Local knowledge base article.

Download Local Log

The easiest option to collect your logs is to simply download all log files as a zip. This can be done within the Local app itself.

  1. Open the Local desktop application
  2. Click Get Help (the icon is a question mark)

If working with Support, please provide us with the entire zip file. Providing logs in this way helps provide more context for any issues you may be experiencing.

Reveal Local’s Log

Alternatively, if the full zip is not desired, logs can also be viewed from the Help menu. These logs do not give as much context for Support and are not suggested for extensive troubleshooting.

  1. Open the Local app on your machine
  2. Click the Help menu
  3. Select Reveal Local’s Log
  4. Attach this file when request to a ticket or chat

Log File Locations

If you’d prefer to locate the file on your own, you will need to check in the appropriate location for your operating system.

Mac: ~/Library/Logs/local-lightning.log

Windows: %AppData%RoamingLocallocal-lightning.log

Linux: ~/.config/Local/local-lightning.log

NEXT STEP: Learn how to connect to the WP Engine API

Still need help? Contact support.

We offer support 24 hours a day, 7 days a week, 365 days a year. Log in to your account to get expert one-on-one help.

The best in WordPress hosting.

See why more customers prefer WP Engine over the competition.