node-google-backup: Automated Local Backups for Google Mail, Calendar, and Contacts

node-google-backup: Automated Local Backups for Google Mail, Calendar, and Contacts

Summary

node-google-backup is a powerful command-line utility designed to automatically back up your Google Mail, Calendar, and Contacts to local files. This JavaScript-based tool ensures your critical data is safely stored offline, providing peace of mind against account lockouts or data loss. It efficiently syncs only new mails, contacts, and events, making subsequent backups quick and resource-friendly.

Repository Info

Updated on October 12, 2025
View on GitHub

Tags

JavaScriptGoogleBackupCLIMailCalendarContactsData Security

Click on any tag to explore related repositories

Introduction

node-google-backup is an efficient command-line utility developed by WeeJeWel, designed to automate the backup of your Google Mail, Calendar, and Contacts to local files. This JavaScript-based tool ensures your valuable data is securely stored offline, offering peace of mind against potential account lockouts or data loss. It intelligently syncs only new mails, contacts, and events, making subsequent backup operations fast and resource-efficient. With 408 stars and 16 forks, it's a well-regarded project licensed under GPL-3.0.

The utility creates a structured local directory, organizing your data into Contacts (VCF files), Calendar (ICS files), and Mail (EML files, categorized by ID, Thread, and Label).

Installation

Before running node-google-backup, you need to create a Google App Password. This provides a secure way for the utility to access your Google services without using your main account password. You can generate one at https://myaccount.google.com/apppasswords.

Once you have your App Password, you can run the utility using Node.js or Docker.

Examples

Node.js

If you have Node.js installed, you can execute the utility directly using npx:

$ npx -y google-backup \
  --username "john.doe@gmail.com" \
  --password "abcd efgh ijkl mnop" \
  --filepath "~/Backups/Google/"

This command will download your Google data to the specified filepath. For automated backups, consider scheduling this command as a cron job.

Docker

For those who prefer containerized environments, node-google-backup is also available as a Docker image:

$ docker run \
  --env GOOGLE_BACKUP_USERNAME="john.doe@gmail.com" \
  --env GOOGLE_BACKUP_PASSWORD="abcd efgh ijkl mnop" \
  --env GOOGLE_BACKUP_FILEPATH="/backups" \
  --env GOOGLE_BACKUP_SERVICES="mail,calendar,contacts" \
  --volume="~/Backups/Google/:/backups/" \
  ghcr.io/weejewel/google-backup

This Docker command mounts a local directory to store the backups and uses environment variables for configuration.

Why Use It?

While Google provides excellent services, there are numerous accounts of individuals being locked out of their accounts, leading to potential loss of critical personal data. node-google-backup addresses this concern by empowering you to maintain local copies of your Google Mail, Calendar, and Contacts. This ensures that you always have access to your data, regardless of your Google account status, providing an essential layer of personal data security and control.

Links