django-ical

library1.9.2pypypi✓ verified 86d ago

django-ical is a simple library/framework for creating iCal feeds based on Django's syndication feed framework. It extends Django's built-in feed system to support iCalendar-specific properties and uses the `icalendar` library for generation. The current version is 1.9.2, and it is actively maintained by Jazzband.

web-framework serialization

pip install django-ical

github ↗package ↗

INSTALL

IMPORT

SIG · DJANGO-ICAL

django-ical

web-frameworkpythonv1.9.2

Install

4.1s avg

Import

916ms

Disk

75MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.9.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 0.965s · 75.4MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 4.1s · import 0.866s · 76MB

75MB installed

● package 75MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ICalFeed

✓ from django_ical.views import ICalFeed

This is the primary class for defining iCalendar feeds, inheriting from Django's `Feed`.

To create an iCal feed, define a model for your events, then create a subclass of `ICalFeed`. This class should implement methods like `items()`, `item_title()`, `item_description()`, `item_start_datetime()`, and critically, `item_guid()` for unique event identification. Finally, wire it into your `urls.py`.

from django.db import models from django.urls import path from django_ical.views import ICalFeed # models.py (example in an app like 'myapp') class Event(models.Model): title = models.CharField(max_length=200) description = models.TextField() start_datetime = models.DateTimeField() end_datetime = models.DateTimeField(null=True, blank=True) created_at = models.DateTimeField(auto_now_add=True) def __str__(self): return self.title # feeds.py (example in 'myapp/feeds.py') class EventFeed(ICalFeed): product_id = '-//example.com//Example Calendar//EN' timezone = 'UTC' file_name = 'events.ics' def title(self, obj): return 'My Example Calendar' def description(self, obj): return 'A calendar feed for all events.' def items(self): return Event.objects.all().order_by('-start_datetime') def item_title(self, item): return item.title def item_description(self, item): return item.description def item_start_datetime(self, item): return item.start_datetime def item_end_datetime(self, item): return item.end_datetime def item_guid(self, item): return f"event-{item.id}@example.com" # urls.py (example in your project's urls.py) # from myapp.feeds import EventFeed # urlpatterns = [ # # ... other urls # path('calendar/events.ics', EventFeed()), # ]

Debug

Known issues

gotchaEvents may not appear or update correctly in calendar clients if `item_guid()` does not return a globally unique identifier for each event. Many clients rely on this for proper syncing and deduplication.

fix

Ensure `item_guid(self, item)` returns a truly unique string for each event, often by combining a unique database ID with a domain name, e.g., `f"event-{item.id}@yourdomain.com"`.

affects: All versions

gotchaBy default, `django-ical` does not set the `Content-Disposition` HTTP header, which means downloaded `.ics` files might not have a suggested filename in browsers.

fix

Set the `file_name` attribute on your `ICalFeed` subclass (e.g., `file_name = 'events.ics'`). This can also be a method for dynamic filenames.

affects: All versions

gotchaUnlike Django's standard syndication feeds, `django-ical` ignores the `item_link` property.

fix

Do not rely on `item_link` for iCal feeds. The iCalendar standard uses `URL` for event links, which is not directly exposed as `item_link` but can be manually added as an extra property if needed via `item_extra_properties`.

affects: All versions

gotchaRetrieving many related objects within `items()` or `item_*` methods can lead to 'N+1' query problems, severely degrading performance for large calendars.

fix

Optimize your `items()` method using `select_related()` or `prefetch_related()` for related data. Avoid complex lookups in `item_*` methods if possible, or ensure data is pre-fetched.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'django_ical'

The `django_ical` application is not included in your Django project's `INSTALLED_APPS` setting, or the package was not installed.

fix

Ensure you have run `pip install django-ical` and added `'django_ical'` to your `INSTALLED_APPS` list in `settings.py`.

Calendar client (e.g., Google Calendar, Apple Calendar) only shows the latest event or fails to update/add new events from the feed.

The `item_guid` method in your `ICalFeed` subclass is either missing or does not generate a unique identifier for each event.

fix

Implement or review your `item_guid(self, item)` method to return a string that is universally unique for each distinct event, typically by embedding the event's primary key and your domain, e.g., `return f"event-{item.id}@yourdomain.com"`.

The downloaded .ics file appears corrupted or invalid according to a calendar validator, possibly due to incorrect newline formatting (e.g., 'invalid newline format').

While `django-ical` generally handles newlines correctly through `icalendar`, if you're attempting custom `HttpResponse` manipulation, newline characters might be rendered incorrectly for the iCal standard.

fix

Ensure that `HttpResponse` objects intended to serve `.ics` files have the correct `Content-Type` header (`'text/calendar'`) and that any manually generated iCalendar content uses `\r\n` for newlines as required by RFC 2445. `django-ical`'s `ICalFeed` handles this automatically.

Upgrade

Version history

1.9.2latest on PyPI · released Jun 12, 2023

Audit

Dependencies

DjangorequiredCore web framework integration; requires Django >= 1.3.

icalendarrequiredUsed under the hood to generate iCalendar data.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/jazzband/django-ical ↗

packagehttps://pypi.org/project/django-ical/ ↗