Machine name

A machine name is the lowercase identifier Drupal gives to a content type, field, vocabulary or view, used by code and configuration instead of its label.

Learn DrupalDrupal glossary
Edited by Founder and CEO, DXPR Last updated

A machine name is the unique identifier Drupal uses behind the scenes for an item such as a content type, a field, a vocabulary or a block. The label is for people; the machine name is for code and configuration files. It uses only lowercase letters, numbers and underscores, and once a bundle such as a content type is saved, its machine name cannot change.

How machine names work in Drupal 11

When you create an item in the admin interface, Drupal builds the machine name from the label you type. The user guide notes that the name is generated automatically from the label and that you can click Edit to override it. The form element behind this is MachineName. It checks that the value is unique through an exists callback, and a small script fills the value in as you type in the source field.

By default the element disallows anything outside a-z, 0-9 and the underscore, and replaces other characters with an underscore. Its default maximum length is 64 characters, although a specific form can set a different limit.

For configuration items such as a content type, the machine name is the ID. The configuration name of a content type starts with node.type., followed by its machine name; the Drush config:status help uses that prefix to list content types. For an entity type, the id value in its definition is the machine name of the type itself, for example node.

Example

Go to Structure › Content types › Add content type and type Case study as the name. Drupal proposes case_study as the machine name. Fix it now if you want a different value, because after you save, the bundle keeps that identifier. Later, in a template, a view or a custom module, you refer to the content type as case_study and never as "Case study".

Common mistakes

  • Accepting a bad generated name. A long, clumsy label produces a long, clumsy machine name. Shorten it before the first save.
  • Trying to rename a bundle. Core blocks it: when a bundle's identifier changes on save, ConfigEntityBundleBase throws a ConfigNameException saying the machine name of the bundle cannot be changed. Renaming the label is fine; renaming the identifier is not.
  • Confusing the label with the machine name in code. A template or query that uses the label breaks the day an editor corrects a typo in it.
  • Reusing a name. The element's uniqueness check stops duplicates within the same type of item, so pick a name that says what the item is for.

For marketing and content teams

You will meet machine names when someone asks for a new content type, a new field or a new category list. Choose the label freely, but agree on the machine name with your developer first, because it is the part that is hard to change. Developers will use it in requests such as "add the summary to the case_study template". Keep the label friendly and treat the machine name as a fixed ID.

Add content type form: after typing Case study in the Name field, Drupal shows the machine name case_study.

Type a name and Drupal proposes the machine name next to the field; click Edit to change it before you save.

Sources

Questions about Machine name

The label is the human-readable name an editor sees, such as Blog post. The machine name is the identifier that code and configuration use, such as blog_post. You can edit a label later; the machine name of a saved bundle stays fixed.

Not for a saved bundle such as a content type: Drupal core throws an error when its identifier changes on save. The safe route is to create a new item with the right machine name and move your content or settings across.

The default Drupal form element rejects everything except lowercase letters, numbers and underscores, and it replaces other characters with an underscore. A specific form can set its own pattern and length, so check the field when you create the item.

Drupal fills the machine name in from the label while you type, so you rarely have to invent it. The Edit link next to the generated value lets you override it before you save.

Related terms

All Drupal terms from A to Z