The ICS file (.ics)

An ICS file is a calendar in a text file. It uses the iCalendar format, which every mainstream calendar app can read and write, so it is how calendar data moves between Google Calendar, Outlook, Apple Calendar and everything else.

You meet ICS files in two forms. As a file: the "Add to calendar" download on a ticket or booking page, an invitation attached to an email, or a calendar exported from an app. And as a link: public holiday calendars, school terms, sports fixtures and shift rotas are often published as an .ics address that calendar apps subscribe to and check again from time to time.

Three things an ICS file is not:

• Not a live connection by itself. A downloaded file is a snapshot. Only a subscription to the file's web address picks up later changes.
• Not a contact card. Contacts use the related vCard format (.vcf). The two look alike inside, with the same BEGIN: and END: lines.
• Not an app's own database. Google, Outlook and Apple store calendars their own way and use iCalendar to exchange them, so app-specific features (colours, some reminders, attachments) may not survive the trip.

Importing copies the events in the file into one of your calendars, once. Later changes to the file never reach you, and you can edit the copies. Subscribing adds the file's web address as a separate, read-only calendar, which your app downloads again on its own schedule. When the publisher replaces the file at that address, subscribers see the change after their app's next check.

A webcal:// link is an ordinary web address with the scheme swapped, as in webcal://example.com/team.ics. Clicking it opens the calendar app the device has registered for webcal, which offers to subscribe instead of downloading the file. That app is often not the one people use (a Google Calendar user on a Mac may get Apple Calendar), so publish the plain https:// address too, for pasting into a From URL box.

Every event needs a UID and a DTSTAMP, and a DTSTART unless the file is a scheduling message with a METHOD. The calendar itself needs VERSION and PRODID. Everything else is optional.

The text itself has three rules that hand-written and home-made files often break:

• Lines end with CRLF (a carriage return and a line feed), as in email. Many apps accept plain line feeds; strict parsers don't.
• Long lines are folded. A line should be at most 75 octets (bytes, not characters), and a longer one continues on the next line after one space. RFC 5545 calls a fold in the middle of a multi-byte UTF-8 character improper and asks readers to repair it, but it's safer to fold between characters.
• Text values are escaped: \, for a comma, \; for a semicolon, \\ for a backslash, and \n for a line break.

Most wrong-time problems come from the way a time is written. iCalendar has three forms, plus dates for all-day events:

• Every TZID needs a VTIMEZONE. RFC 5545 requires the file to define each time zone it names. Many apps recognise names like Europe/Amsterdam without one, but not all do, and Outlook writes Windows names such as W. Europe Standard Time, which only the included definition explains.
• Floating times look right to the author and wrong to everyone in another time zone. A generator that drops the Z or the TZID produces them by accident.
• An end date is not included. An all-day event from 2 to 4 December has DTEND;VALUE=DATE:20261205. Writing 20261204 makes it end a day early.
• Recurring events should use a TZID. A weekly 10:00 meeting written in UTC moves by an hour for local attendees when summer time starts or ends.

A repeating event is stored once, with an RRULE that describes the pattern. The calendar app works out the dates. DTSTART is always the first occurrence.

• EXDATE removes an occurrence, such as a meeting cancelled for a public holiday. Its time must match the occurrence exactly, time zone included.
• A moved or edited occurrence is a second VEVENT with the same UID and a RECURRENCE-ID naming the original date and time.
• UNTIL must be in UTC when DTSTART has a time zone or is in UTC. A local UNTIL breaks that rule, and apps then disagree about where the series ends, or reject it.
• RDATE adds extra dates that don't follow the pattern.

An event's identity is its UID, not its title or time. When an app receives an event whose UID it already has, it treats it as a new version of that event. SEQUENCE says which version is newer: it starts at 0, and the organiser raises it for each significant change, such as a new time or place.

• Duplicates after a second import usually mean the file was generated with new UIDs, or the app imports without checking them. Keep UIDs stable and prefer a subscription for anything that changes.
• An updated invitation that changes nothing often has the same SEQUENCE as the old one. Raise it with every real change.
• Cancelling an invitation means sending METHOD:CANCEL with the same UID. In a published calendar, set STATUS:CANCELLED on the event or remove it from the file.

Apps also differ in what they keep. Some ignore alarms in imported or subscribed calendars (Apple Calendar removes them unless you untick Remove alerts when subscribing), and support for to-dos, attachments and colours varies widely. Test with the apps your audience actually uses.

• Open it: double-click it, and your default calendar app offers to add the events. On a phone, tap it in the email or browser; Google Calendar's own import only works on a computer.
• Read it: open it in any text editor. Each line is one property, so a quick look shows the times and time zones it really contains.
• Edit it: use a plain-text editor and keep the line endings as CRLF (VS Code shows CRLF or LF in its status bar). Raise SEQUENCE and keep UID unchanged if the event was already shared.
• Create one: export it from a calendar app, or generate it with a library such as icalendar for Python or ical-generator for Node.js rather than by string concatenation, which tends to get folding and escaping wrong.
• From a spreadsheet: Google Calendar can import CSV directly. To turn CSV into ICS, a short script with an iCalendar library is the reliable route.

An ICS file is text and can't run code. The risks are in what it says and where it points:

• Attendee email addresses. Invitations carry the organiser and every attendee as mailto: addresses, with names and replies. Forwarding or publishing one shares them all. sample-invite.ics below shows what's included.
• Private calendar addresses. Many calendar services offer a private iCal link to a calendar. Anyone who has the link can read every event in it, with no sign-in, so treat it like a password and reset it if it leaks.
• Descriptions and notes often hold dial-in codes, door codes, home addresses or internal details nobody meant to publish.
• Calendar spam. Unknown invitations and subscriptions can add events with phishing links. Apple's advice is to subscribe only to calendars from sources you trust, and Apple Calendar can report a subscription as junk when you unsubscribe.