skip to content

What is an archetype catalog (archetype-catalog.xml) and how does Maven decide which archetypes are offered during generation?

level: middleimportance: should knowfreq 35%

answer

  1. archetype-catalog.xml = index of templates
  2. -DarchetypeCatalog local/internal/remote/URL
  3. ~/.m2/archetype-catalog.xml = local
  4. archetype:crawl builds a catalog
  5. catalog = discovery, repo = resolution

basics

~10 s

A catalog is an XML file listing available archetypes by coordinates. archetype:generate reads catalogs (local, internal, remote, or a custom URL) and shows you that list to pick from.

solid answer

~40 s

An **archetype catalog** is an `archetype-catalog.xml` document that enumerates archetypes — each entry has groupId, artifactId, version, and a description. When you run `archetype:generate`, the plugin gathers archetypes from one or more catalogs selected via `-DarchetypeCatalog`. Recognized values include `local` (`~/.m2/archetype-catalog.xml` and locally installed archetypes), `internal` (a list bundled in the plugin), `remote` (historically Maven Central's catalog), and any explicit URL or file path. The merged list is what the wizard presents. In modern Maven, the giant Central catalog is large/slow, so teams usually host their own catalog (generated with `archetype:crawl` or maintained by hand) and point `-DarchetypeCatalog` at it, or skip the catalog entirely by passing the archetype coordinates directly. Catalogs are just discovery metadata — the archetype artifacts themselves still resolve from a repository.

code

bash · 6 lines
bash
# Use a company-hosted catalog
mvn archetype:generate \
  -DarchetypeCatalog=https://nexus.example.com/repository/maven-public/archetype-catalog.xml

# Or only local catalog
mvn archetype:generate -DarchetypeCatalog=local

go deeper

for a junior

Knows the wizard shows a list you pick from.

for a middle

Understands archetype-catalog.xml, the local/internal/remote/URL options, and that catalogs are discovery metadata.

for a senior

Hosts an internal catalog, manages auth/mirrors for resolution, and chooses catalog vs direct coordinates per workflow.

for a principal

Owns the org catalog lifecycle (crawl/refresh, curation, deprecation) and integrates it into developer tooling and repo governance.

## The problem catalogs solve There are thousands of archetypes. `archetype:generate` needs a way to *list* the ones you can choose. An **archetype catalog** is that index: an XML file named `archetype-catalog.xml` listing archetypes by coordinates. ## Catalog structure ```xml <archetype-catalog> <archetypes> <archetype> <groupId>com.example.archetypes</groupId> <artifactId>service-archetype</artifactId> <version>2.1.0</version> <description>Standard microservice template</description> <repository>https://nexus.example.com/repository/maven-releases</repository> </archetype> </archetypes> </archetype-catalog> ``` Each `<archetype>` is pure metadata pointing at an artifact; the actual template JAR is downloaded from a repository when you generate. ## How Maven picks catalogs The `-DarchetypeCatalog` property selects the source(s). Recognized keywords and forms: - `local` — `~/.m2/archetype-catalog.xml` plus archetypes already installed in your local repo. - `internal` — a built-in list bundled inside the archetype plugin (a handful of Apache archetypes). - `remote` — historically the Maven Central catalog (very large; often slow or disabled in newer plugin versions). - An explicit **URL** (`-DarchetypeCatalog=https://nexus.example.com/.../archetype-catalog.xml`) or **file path**. - Multiple comma-separated values are merged. The wizard then shows the merged set and lets you filter by typing part of the name. ## Generating a catalog `mvn archetype:crawl` walks a repository directory and emits an `archetype-catalog.xml` for everything it finds, which is how an internal Nexus/Artifactory catalog gets built and refreshed. ## Skipping the catalog If you already know the archetype coordinates, pass them directly (`-DarchetypeGroupId/ArtifactId/Version`) and no catalog lookup is needed — the common pattern in CI. ## Key point A catalog is *discovery only*. Resolution of the archetype artifact still follows normal Maven repository rules (settings.xml mirrors, repositories, auth).

  • Why do teams avoid -DarchetypeCatalog=remote today?
    The Central catalog is enormous and slow to download/parse, and newer plugin versions de-emphasize it. Teams host a small internal catalog or pass archetype coordinates directly instead.
  • How is a custom catalog generated for an internal repository?
    Run mvn archetype:crawl pointed at the repository directory; it produces an archetype-catalog.xml listing every archetype found, which you publish on the repo server.

saying these in an interview costs you the question

  • Assuming the catalog stores the actual template code — it only stores coordinates/metadata; the JAR resolves from a repository.
  • Thinking 'local' means the project directory; it means ~/.m2 and locally installed archetypes.

context

resolving links…