Developer · Guide
How to Cache Data With Transients in WordPress

Short answer
To cache data with transients in WordPress, call set_transient() with a name, a value, and an expiration time in seconds. Read it back with get_transient() and rebuild the value only when it returns false. Delete it with delete_transient() when the source data changes.
Key takeaways
- A transient stores a named value for a set time, then drops it when it expires.
- set_transient() takes a name, a value, and an expiration in seconds, and returns true when set.
- get_transient() returns the stored value or false, so check it with a strict false comparison.
- Transient names must be 172 characters or fewer, or they will silently fail.
- Expiration is a maximum life, not a promise, so code must always rebuild a missing value.
- With a persistent object cache, transients move from the database into memory with no code change.
What is a WordPress transient?
A transient is a named piece of data that WordPress stores for a set time, then drops when it expires.
Developer.WordPress.org states that the Transients API is used to temporarily store information in WordPress across page loads (checked November 2026).
Use a transient when the same data is slow to build and safe to reuse. A weather feed, a remote API reply, or a list of post IDs are good fits.
A transient is not a place for data that must never disappear. Developer.WordPress.org states that a transient may vanish before its expiration time, so your code must always cope with a missing value (checked November 2026).
A guide on page cache vs object cache explains how transients sit beside the other caching layers on a WordPress site.
What do you need before you start?
You need a WordPress site you can edit, access to your theme or plugin files, and one slow piece of data to cache.
Work on a staging copy first when the site is live. A bad cache key can hide fresh content, and staging lets you spot that before visitors do.
Pick the data and the key name before you write code. The key is a short string such as mysite_weather_data, and it names the stored value.
Keep the key short. Developer.WordPress.org states that a transient name must be 172 characters or fewer in length (checked November 2026).
Use a prefix tied to your site or plugin, such as mysite_. A prefix stops your key from clashing with a key set by another plugin.
Check the PHP version your site runs. WordPress.org states that WordPress recommends PHP 8.3 or greater, and that WordPress still works with PHP 7.4 and later in older setups (checked November 2026).
How do you save data with set_transient?
Save data with set_transient(), passing a name, a value, and an expiration time in seconds.
Developer.WordPress.org states that set_transient() accepts three parameters, which are the name of the transient, the data to be stored, and an optional expiration time in seconds (checked November 2026).
The same page states that the function returns true if the transient was set (checked November 2026).
A one-week example looks like this:
set_transient( 'dev-blog-transient', 'Some data I want to persist', WEEK_IN_SECONDS );
WordPress ships time constants so you do not have to count seconds by hand. HOUR_IN_SECONDS, DAY_IN_SECONDS, and WEEK_IN_SECONDS name the periods they describe.
You can store strings, numbers, arrays, and objects. WordPress serializes arrays and objects when it saves them, so you get the same shape back when you read the value. PHP.net states that serialize() generates a storable representation of a value, so its type and structure survive storage (checked November 2026).
Call set_transient() again with the same name to replace the stored value. The old value is dropped and the new expiration time starts from that call.
How do you read data with get_transient?
Read data with get_transient(), passing only the transient name, and check the result with a strict comparison to false.
Developer.WordPress.org states that get_transient() accepts a single parameter, the name of the transient, and returns the data or false if the transient does not exist or has expired (checked November 2026).
Use false === in the check, not a loose comparison. Developer.WordPress.org states that strict comparison protects you when the stored data is a value such as the number zero, which would look empty in a loose check (checked November 2026).
The standard pattern is to read first and rebuild only on a miss:
if ( false === ( $data = get_transient( 'mysite_weather_data' ) ) ) {
$data = fetch_weather_data();
set_transient( 'mysite_weather_data', $data, HOUR_IN_SECONDS );
}
This pattern keeps the slow work off most page loads. The slow fetch runs only when the transient is missing or expired.
A guide on how to find slow plugins in WordPress shows how to spot the slow work that is worth caching in this way.
How do you delete a transient?
Delete a transient with delete_transient(), passing the transient name, when the stored data is stale.
Developer.WordPress.org states that any transient can be deleted at any time with delete_transient(), and that it returns true if the transient was deleted (checked November 2026).
The call is short:
delete_transient( 'mysite_weather_data' );
Delete the transient when the source data changes, not only when it expires. A post save, a settings save, or a product update are the right moments to clear a related key.
For a site-wide value on a Multisite network, use the site versions instead. set_site_transient(), get_site_transient(), and delete_site_transient() work the same way across the network.
A guide on how to optimize the WordPress database covers how stored options and expired transients build up in the database over time.
How do you pick an expiration time?
Pick an expiration time that matches how often the source data changes, and treat it as a maximum life, not a promise.
Developer.WordPress.org states that transient expiration times are a maximum time, with no minimum age, so a transient may disappear one second after you set it (checked November 2026).
That means a long expiration never guarantees the data will last that long. Your code must rebuild the value whenever get_transient() returns false.
| Data type | Suggested expiration | Why |
|---|---|---|
| Remote API reply | 1 hour | APIs change often and may rate-limit repeat calls |
| List of post IDs | 1 week | Post lists change only when content changes |
| Rendered markup block | 12 hours | Markup is slow to build and changes rarely |
| Weather or price feed | 15 minutes | The source value changes through the day |
Always set an expiration time, even a short one. Developer.WordPress.org states that leaving it out defaults to 0 seconds, and a transient with no expiration is marked to autoload on every page load (checked November 2026).
That autoload behavior can slow every request. The same page states that 1,000 transients with large datasets loaded on every page would have a large effect on site speed (checked November 2026).
A guide on how to set up Redis object cache in WordPress explains the persistent cache that changes where transients live.
Where are transients stored?
Transients live in the database by default, and move to the object cache when a persistent object cache is active.
Developer.WordPress.org states that in a default install, transient data is stored in the options table of the database (checked November 2026).
The same page states that once a persistent cache is in place, the Transients API will no longer store its data in the database and will instead use the object cache to persist its data (checked November 2026).
You do not change your code to gain that speed. Developer.WordPress.org states that no code changes are needed, because the switch is handled under the hood (checked November 2026).
The default object cache is not persistent. Developer.WordPress.org states that anything cached in the default object cache will disappear once the page has finished loading (checked November 2026).
That is why transients are the safer choice for data that must survive across page loads. Developer.WordPress.org states that if you need data to persist in any server setup, you should use the Transients API (checked November 2026).
A guide on Redis vs Memcached for WordPress compares the two common persistent cache backends.
What can you cache with transients?
Cache slow queries, remote API replies, and rendered markup, and skip anything that must stay fresh on every load.
A slow query is the classic case. Developer.WordPress.org states that caching the results of an expensive WP_Query avoids repeat trips to the database when the same results are needed more than once (checked November 2026).
The handbook example stores only post IDs, not full post objects:
if ( false === ( $ids = get_transient( 'dev-blog-post-id-list' ) ) ) {
$query = new WP_Query( array( 'posts_per_page' => 25, 'fields' => 'ids' ) );
$ids = $query->posts;
set_transient( 'dev-blog-post-id-list', $ids, WEEK_IN_SECONDS );
}
Storing IDs keeps the stored value small. Your code can then load the full posts from those IDs when it needs them.
Remote API replies are another strong fit. Developer.WordPress.org states that storing API results in a transient will reduce rate-limit problems and slow responses from the API (checked November 2026).
Rendered markup works too. Developer.WordPress.org states that transients do not always have to store data, and that storing generated markup can be faster than rebuilding it on each load (checked November 2026).
Do not cache a logged-in user page, a cart, or a form result. Those values differ per visitor, so a shared transient would show one visitor data meant for another.
A guide on how to create a WordPress plugin shows where this kind of caching code belongs in a plugin file.
What mistakes should you avoid?
Avoid missing expiration times, plain boolean values, and keys that are too long or too generic.
Do not store a plain boolean. Developer.WordPress.org states that transients should not be used to hold plain boolean values, because false is also the signal for a missing transient (checked November 2026).
Store 1 or 0 in place of true or false, or wrap the boolean in an array. Either form survives the strict false === check without confusion.
Do not build a key from user input without cleaning it. A key with spaces or odd characters is hard to read later, and a long key can fail without warning.
Learn WordPress states that you should not trust any data, and that you should always check that it is valid and safe to use (checked November 2026).
Developer.WordPress.org states that longer key names will silently fail, because WordPress adds a prefix such as _transient_ to the name in the options table (checked November 2026).
Do not treat a transient as a lock or a counter that must be exact. A transient can vanish at any time, so a count stored in one may skip or repeat.
Do not cache a value and then forget to clear it. Add a delete_transient() call to the hook that fires when the source data changes, such as save_post.
How do you check that caching works?
Check that the slow work runs once, that the cached value returns on the next load, and that clearing the key forces a rebuild.
Add a short note to a log or a comment in the code while you check, then remove it. Load the page twice and watch for the slow step, such as the remote API call, to run only on the first load.
Then delete the transient and load the page again. The slow step should run once more, and the fresh value should be stored again.
Check the options table when a value looks wrong. A transient with an expiration appears as two rows, one for the value and one for the timeout, both starting with _transient_.
If the value never appears, check three things: the key is 172 characters or fewer, the expiration is greater than zero, and the code that sets the transient actually runs on that page.
If the value is stale after an edit, check that your save hook deletes the key. A missing delete call is the most common cause of a page that never updates.
Frequently asked questions
Can transients fill up the WordPress database?
Yes, if the transient is stored in the database without a persistent object cache. Expired transients can stay in the options table until WordPress cleans them, so a site that sets many short-lived transients can build up rows. Set an expiration on every transient and delete keys you no longer need.
When should I use transients instead of wp_cache_set()?
Use transients when the data must survive across page loads on any server, including one without a persistent object cache. Use wp_cache_set() only for data that is needed during the current page load, because the default object cache is cleared when the page finishes loading.
Does a transient always last until its expiration time?
No. A transient is a maximum life, not a promise. It can disappear before its expiration time if the object cache is purged or the database changes. Always write code that rebuilds the value when get_transient() returns false.
Can I store user-specific data in a transient?
No. A transient is shared across visitors, so a value that differs per user, such as a cart, a login state, or a form result, must not be stored in one. Cache only data that is the same for every visitor who sees it.
Why does my transient never return a value?
First check that the key is 172 characters or fewer and that the expiration is greater than zero. Then check that the code which sets the transient runs on that page, and that no save hook or other code deletes the key right after it is set.
Do transients work on a Multisite network?
Yes. On a Multisite network, use set_site_transient(), get_site_transient(), and delete_site_transient() for values shared across the network. The single-site functions store the value for one site only.
Sources
- An introduction to the Transients API WordPress Developer Resources
- set_transient() WordPress Developer Resources
- get_transient() WordPress Developer Resources
- delete_transient() WordPress Developer Resources
- WP_Query WordPress Developer Resources
- Requirements WordPress.org
- serialize() PHP.net
- Securely developing plugins and themes Learn WordPress
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


