Nearly every major component that makes up a Drupal site is an entity of one type or another, e.g. users, nodes, and blocks are all types of entities. All entities can then be customized by adding fields to them. Understanding how Drupal's Entity system works is fundamental to understanding the similarities and differences between the main components that make up a Drupal site. You can alter existing entity types to make them work more efficiently for your site, and it's also possible to create your own entity types to encapsulate the behavior of specific data structures within your application.

Example tasks

  • Understand what components of a Drupal site are entities
  • Understand the difference between configuration and content entities
  • Know when, and how to create custom entities


At this point the Entities are relatively stable. Any major changes to the API at this point are likely to be new features, or slight changes in best practices as they emerge. The fundamentals and main components of the system are unlikely to change rapidly.

Drupalize.Me resources

Entities and fields are closely related and the boundaries between the two are often confused. It's generally a good idea to learn both in order to properly use either one.

More Guides

We have guides on many Drupal skills and topics.

Explore guides

External resources

  • 2.3 Concept: Content Entities and Fields (

    • A high level overview of how, and why, Drupal uses entities and fields to organize content.
  • Introduction to Entity API in Drupal 8 (

    • While largely still a work in progress, this is the location of the Entity API documentation on Many of the sub-pages linked from this landing page are more complete.
  • Working with the Entity API (

    • This page on provides a quick reference for the main commands used when interacting with entities.
  • Entity API (

    • Technical documentation for the Entity API. Useful when you already understand the concept of entities but are unsure how to implement a feature or accomplish a specific task.
  • Example for Developers (

    • The examples project contains example modules with code that demonstrates creating both content and configuration entities.