Upgrade Guide - Version 5

Welcome to the upgrade guide for Advanced Custom Fields version 5. This guide will walk you through the update process and answer any questions you may have about our most exciting version yet!

On this page: Upgrade Steps - Whats New - Developer Notes - FAQ

Upgrade Steps

Upgrading ACF to version 5 is simple, here's how.

1 Update the Advanced Custom Fields plugin.

Log into your WordPress website and use the Plugins page to view and update the Advanced Custom Fields plugin.

2 Update any Premium Add-ons.

Does this website use the Repeater field, Flexible Content field, Gallery field or Options Page add-ons? Be sure to update these too.

3Perform the Database Upgrade.

Version 5 uses a much smarter way to organise field groups and will need to create some extra data before it is ready for use.


Nice work, you are now updated! Be sure to take a quick look over your website to ensure everything is as it should be and don't hesitate to contact our support team with any questions or concerns.

What's New?

Here's a look at the new and exciting features in ACF version 5!

Link Field

The Link field provides a simple way to select or define a link (url, title, target).

Group Field

The Group field provides a simple way to create a group of fields.

oEmbed Field

The oEmbed field allows an easy way to embed videos, images, tweets, audio, and other content.

Clone Field Pro

The clone field allows you to select and display existing fields.


More fields use AJAX powered search to speed up page loading

Local JSON

New auto export to JSON feature improves speed and allows for syncronisation. Learn more

Easy Import / Export

Both import and export can easily be done through a new tools page

New Form Locations

Fields can now be mapped to menus, menu items, comments, widgets and all user forms!

More Customization

New PHP (and JS) actions and filters have been added to allow for more customization

Fresh UI

The entire plugin has had a design refresh including new field types, settings and design!

New Settings

Field group settings have been added for label placement and instruction placement

Better Front End Forms

acf_form() can now create a new post on submission with lots of new settings

Better Validation

Form validation is now done via PHP + AJAX in favour of only JS

Moving Fields

New field group functionality allows you to move a field between groups & parents

Developer Notes

We made some changes. Here are the ones you should know about.

Name Notes
ACF PRO We've moved away from selling individual add-ons towards an all inclusive PRO version! This pro version bundles together ACF + 5 features into 1 easy to access plugin! Changing to this new platform allows us to do 2 important things; Firstly, to provide more updates & features from our end, and secondly, to reduce the time time & effort needed to maintain the ACF plugins from your end.
Add-ons We don't want to leave any of our amazing customers worried about past projects, and this is why we have released updates for all ACF Add-ons making them fully compatible with ACF version 5!
Database Upgrade After updating to ACF version 5, you will be prompted to upgrade the Database. This is a necessary step to migrate field group settings over to their new location (discussed in 'Field Groups' notes). This upgrade will also copy across any taxonomy term values from the 'wp_options' table to the newly used 'wp_termmeta' table! Please note this upgrade will not delete or remove any data.
Template Functions No changes to report here. You can expect every get_field() and the_field() to work just the same! We have, however, improved logic and added some new functions!
Field Groups Field group settings are now saved with a post_type of 'acf-field-group' (previously 'acf'). New settings have also been added including active, label_placement, instructions_placement and description.
Fields Field settings are now also saved to the wp_posts table with a post type of 'acf-field'. Many new settings have been added to each field type!
wp_termmeta Taxonomy term custom field values are now saved to the 'wp_termmeta' table! These values were previously saved to the wp_options table. The database upgrade will also copy across all term custom field values to the wp_termmeta table.
select2 ACF version 5 includes the Select2 JS library for powerful AJAX based selection in many of it's field's (select, post_type, taxonomy, user)!
Admin HTML Class names for field elements have changed from .field_type-{$type} to .acf-field-{$type}. If your theme contains custom CSS or JS which relies on the old field class names, you can add them back by adding the following line of code to your functions.php file: add_filter('acf/compatibility/field_wrapper_class', '__return_true');
$_POST Field values will now be sent in the $_POST data using $_POST['acf'] instead of $_POST['fields'].
Export ACF version 5 includes a .json based export and import tool. Previous version of ACF used the WP .xml export which will no longer be compatible.


Have questions? We have answers.

Where is the update?

Please be aware that ACF version 5 is currently undergoing beta testing and will not be released as a 'one-click' update until later this year. If you wish to download and install the version 5 manually, please see the Beta Test - Version 5 guide.

Do I need to make any changes?

No, you do not need to make any changes to your theme. ACF version 5 is still the same plugin you use and love, and will work in the same way. If your theme contains heavy ACF customisation, it will be wise to review your code and check for any issues.

Will my Add-ons work?

Yes, we have released updates for all official ACF Add-ons (Repeater, Gallery, Flexible Content & Options Page) making them fully compatible with ACF version 5! Please update your ACF add-ons to version 2.

Do I need to buy ACF 5?

No, ACF version 5 is a free update. If you require professional features such as the repeater field, please take a look at the ACF PRO page here.

Can I roll back?

Yes, although it is a manual process. All versions of the ACF plugin can be found here. Simply download, extract and replace your 'plugins/advanced-custom-fields' plugin folder

Should I backup?

It is always a good idea to backup your website before updating a plugin to a new major version, however, this is not required. ACF version 5 does not delete or modify any existing data during the 'DB Upgrade' - only new data is created.