WordPress term_exists Example: Avoid Duplicate Terms in Imports

Last reviewed: April 28, 2026

Term creation code becomes fragile when every run blindly inserts categories or tags and hopes duplicates will sort themselves out. term_exists() is the safer first step for importers, seeders, and plugin setup flows that need stable taxonomy state.

This guide shows how to use term_exists() to check for an existing term before insert or assignment logic continues.

Check for an existing term by slug

<?php
$existing = term_exists( 'security-notes', 'category' );

if ( $existing ) {
	$term_id = (int) $existing['term_id'];
}

Slug-based checks are usually the most reliable choice in automated workflows because labels can change while the canonical identifier stays stable.

Fallback to insert only when the term is missing

$existing = term_exists( 'security-notes', 'category' );

if ( ! $existing ) {
	$created = wp_insert_term(
		'Security Notes',
		'category',
		array(
			'slug' => 'security-notes',
		)
	);

	if ( is_wp_error( $created ) ) {
		return $created;
	}

	$term_id = (int) $created['term_id'];
} else {
	$term_id = (int) $existing['term_id'];
}

This pattern makes seed routines safe to rerun without spraying near-duplicate categories across the site.

Use the parent argument for hierarchical taxonomies when needed

If the taxonomy is hierarchical and sibling terms can share the same label under different parents, pass the parent term context so the existence check stays precise.

Interpret the return shape correctly

term_exists() may return null, a string ID, or an array depending on how it is called. Read the result shape carefully instead of assuming one fixed type in every branch.

Production checklist

• Prefer slug checks for automated workflows.
• Use the taxonomy argument explicitly.
• Pass parent context for hierarchical taxonomies when siblings can repeat labels.
• Handle the function’s mixed return values carefully.
• Only call wp_insert_term() when the term is genuinely missing.
• Keep term bootstrap routines rerunnable.

Common mistakes

• Checking by label when the slug is the true identifier. Editorial copy changes more often than slugs.
• Ignoring mixed return types. That causes subtle type bugs in later logic.
• Skipping the taxonomy parameter. The lookup becomes less precise than intended.
• Forgetting parent context in hierarchical taxonomies. Duplicate labels can then resolve incorrectly.
• Inserting first and handling duplication later. The safer pattern is to check before create.

Related reading

If a missing term should be created automatically, continue with the wp_insert_term guide. If the final step is attaching the term to content, use the wp_set_object_terms article.

References and further reading

• WordPress Code Reference: term_exists()
• WordPress Code Reference: wp_insert_term()
• WordPress Code Reference: get_term_by()