wp_count_terms: count taxonomy terms
Returns how many terms a taxonomy contains. The companion to the term listings, which return no total of their own.
Arguments
| Argument | Required | Meaning |
|---|---|---|
taxonomy |
Yes | The taxonomy key |
Permissions
mcp:read and wp:content:read. No WordPress capability required.
What it returns
A single count.
It counts empty terms too
The count includes terms with no posts. That is deliberate and it is the right behaviour for the question this tool usually answers — "how big is this taxonomy?" — because unused terms are part of the mess you may be trying to assess.
It does mean the number can exceed what a visitor would ever encounter. A site with 40 tags in use and 60 abandoned ones reports 100.
It works on any taxonomy
Unlike the listing tools, which are fixed to categories and tags, this accepts any taxonomy key — including custom ones.
That makes it the only tool in this chapter that can tell you anything about a custom taxonomy's terms. For a custom taxonomy there is no dedicated listing tool, so wp_count_terms is how you confirm terms exist at all before working with them.
Get the valid keys from wp_get_taxonomies.
Why it is the first call in a taxonomy job
Term listings cap at 100 per page and report no total, so a listing alone cannot tell you whether you have seen everything.
Count the tags, then list the first 100, and tell me whether that is all of them.
Without the count, an assistant that lists once will reason about a hundred tags as though they were the whole taxonomy — and a cleanup based on that assumption misses whatever came after.
Sizing a reorganisation
The count against the listing's count fields gives you the shape:
wp_count_termsfor the total.- A listing for the individual post counts.
- Compare.
A taxonomy with 200 terms where the listing's first page shows most counts at one or zero is a taxonomy that grew by accident, and the honest recommendation is usually consolidation rather than an assistant-driven cleanup. See Create terms and organize content.
Using it well
Count the terms in "category" and in "post_tag".
How many terms does the "project-type" taxonomy have?
At the start of an unfamiliar site:
List the taxonomies, then count the terms in each, then stop.
What it does not do
- No breakdown. One number, not a distribution.
- No filtering. It counts the taxonomy.
- No IDs or names. Use the listing tools.
- No count of how many posts use the taxonomy. That is the
counton each term.
Common problems
| Symptom | Cause |
|---|---|
| A count of zero for a taxonomy you can see | Wrong taxonomy key; check wp_get_taxonomies |
| Higher than the terms in use | Empty terms are included |
| Disagrees with the WordPress admin | The admin may be hiding empty terms |