DateTimeField - Django Models

DateTimeField is a Django model field used to store both date and time values.

• Represented in Python as a datetime.datetime object.
• Stores a combined date and time value in the database.
• The default form widget is DateTimeInput.
• In Django Admin, it is displayed as two separate inputs (date and time) with JavaScript shortcuts.

Syntax

field_name = models.DateTimeField(**options)

Optional Arguments for DateTimeField

DateTimeField provides some additional useful options:

1. auto_now=True

Automatically sets the field to the current date and time every time the object is saved.

This is commonly used for "last modified" timestamps.

updated_at = models.DateTimeField(auto_now=True)

• The current date/time is always used, it is not just a default value.
• You cannot override it manually.
• The field updates only when calling Model.save().
• It does NOT update when using QuerySet.update() unless you explicitly set it.

Example:

Model.objects.filter(id=1).update(updated_at=timezone.now())

2. auto_now_add=True

Automatically sets the field to the current date and time when the object is first created. This is typically used for creation timestamps.

created_at = models.DateTimeField(auto_now_add=True)

• The value is set only once during creation.
• Even if you provide a value while creating the object, it will be ignored.
• You cannot manually override it.

3. Using default

To keep the field editable or manually modifiable, use default instead of auto_now_add.

from django.utils import timezone
published_at = models.DateTimeField(default=timezone.now)

This is the recommended approach in modern Django projects because it respects USE_TZ=True.

Note: The options auto_now_add, auto_now, and default are mutually exclusive. Any combination of these options will result in an error.

Django Model DateTimeField Example

Consider a project named geeksforgeeks having an app named geeks.

In models.py:

from django.db import models

class GeeksModel(models.Model):
    geeks_field = models.DateTimeField()

    def __str__(self):
        return str(self.geeks_field)

After running makemigrations and migrate, Django creates the corresponding database table with a DateTime column that stores both date and time values.

Opening Django Shell

Validation can be tested interactively by opening the Django shell:

python manage.py shell

Creating an Instance in Shell

Since modern Django projects usually have USE_TZ = True, it is recommended to use timezone-aware datetime values.

from geeks.models import GeeksModel
from django.utils import timezone

GeeksModel.objects.create(
geeks_field=timezone.now()
)

Stored objects can be retrieved using:

GeeksModel.objects.all()

This confirms that the DateTimeField successfully stores a datetime.datetime object in the database.

Validation Using Django Admin

The DateTimeField can also be validated using the Django Admin interface.

Register the Model in geeks/admin.py:

from django.contrib import admin
from .models import GeeksModel

admin.site.register(GeeksModel)

Create a Superuser:

Enter username, email, and password when prompted.

python manage.py createsuperuser

Run the Development Server:

python manage.py runserver

Visit: http://127.0.0.1:8000/admin/ and log in using the superuser credentials, then navigate to the Geeks models section.

New instances can be added from this interface, and saved records can be viewed directly within the admin panel.

Field Options

Field options are arguments provided to a model field to apply constraints or define specific behavior for that field. For example, adding the argument null=True to a DateTimeField allows the corresponding database column to store NULL values in a relational database.
Below are the common field options and attributes that a DateTimeField can use: