Skip to main content

gwbackupy: Google Workspace™ backup and restore solution.

0.2.0 0.2.0 PyPI - Downloads BSD-3-Clause black - GitHub Actions Workflow Status Coverage Status pytest - GitHub Actions Workflow Status

What is it?

Gwbackupy is an open source Google Workspace™ backup and restore solution, written in python.

Currently supported Gmail messages and labels only.

Why?

Due to gmvault limitations:

  • is still abandoned (??)
  • authentication method is not usable in Google Workspace wide
  • designed only for gmail messages
  • only supports IMAP protocol (slow and less security)

Details

  • Run from CLI or run directly from python code

  • Authentication

    • OAUTH for free or paid plans (not recommended for paid plans)
    • Service account file (JSON) for paid plans (can be configured to access all accounts in workspace.)
  • Version controlled storage interface

    Allows to restore specific moments without using an external snapshot system (eg. zips, file system with snapshot). Not limited to file storage and is not limited to the use of a database server. Currently, file system based storage is only available.

  • Dry mode (not write to local storage and not modify on server)

  • API communication (no need for special IMAP and other settings): secure and fast

  • Gmail backup

    • full backup (download all messages, labels)

    • full backup continuously (periodically rerunning)

      Scanning the full mailbox, but download only the new messages and mark the deleted messages.

    • Quick backup (sync the last N days)

  • Gmail restore

    • restore deleted message in specified interval
    • full restore messages and labels to an empty mailbox (e.g. to other gmail account)

Paid plans are the following: here. Google One or additional storages are not considered as paid plans

Requirements

  • python3 and pip

  • Google Cloud account and own created access files. This software does not contain access files, this is for security reasons.

    A credit card is required during registration, but the use of Workspace APIs is free.

Install

The easiest way for installing:

pip install gwbackupy
# and run...
gwbackupy ...

or

# clone this repository
# install requirements
pip install -r requirements.txt
# and run...
python3 -m gwbackupy ...

The project also has an official Docker image: gwbackupy-docker - under development. The docker image has scheduled backup runs and also supports managing multiple email accounts.

Instructions

Usage

Example usage Gmail

Backup run in CLI:

gwbackupy \
  --service-account-key-filepath <service-acount-json-key-file> \
#  --credentials-filepath <client-secret-json> \    # or with OAUTH
  --batch-size 5 \
  gmail backup \
  --email <mailbox email address>

Restore run in CLI:

gwbackupy \
  --service-account-key-filepath <service-acount-json-key-file> \
#  --credentials-filepath <client-secret-json> \    # or with OAUTH
  --batch-size 5 \
  gmail restore \
  --add-label "backup-restore-1231" \
  --add-label "more-restore-label" \
  --filter-date-from <date or datetime eg. "2023-01-01"> \
  --filter-date-to <date or datetime eg. "2023-02-02 03:00:00"> \
  --restore-deleted \
  --email <source backup mailbox email address> \
  --to-email <destination mailbox email address> # If you want to a different destination account

Backup run from python code:

# WARNING: Calling directly from python code actively change in the current state of development.

from gwbackupy.gmail import Gmail
from gwbackupy.storage.file_storage import FileStorage
from gwbackupy.providers.gmail_service_provider import GmailServiceProvider
from gwbackupy.providers.gapi_gmail_service_wrapper import GapiGmailServiceWrapper

storage = FileStorage('./data/email@example.co')
service_provider = GmailServiceProvider(
    service_account_file_path='serviceacc.json',
    storage=storage,
)
service_wrapper = GapiGmailServiceWrapper()
gmail = Gmail(email='email@example.com',
              service_provider=service_provider,
              service_wrapper=service_wrapper,
              batch_size=3,
              storage=storage)
if gmail.backup():
    print('Yeah!')
else:
    print(':(')

Security

See SECURITY.md

Contributing

Welcome! I am happy that you want to make the project better.

Currently, there is no developed documentation for the process, in the meantime, please use issues and pull requests.

Changelog

The changes are contained in CHANGELOG.md.

About

Márton Somogyi

Metadata

Release files for gwbackupy 0.12.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gwbackupy 0.12.0
File Size Uploaded Provenance Actions
gwbackupy-0.12.0.tar.gz 32.9 kB Without provenance Details for gwbackupy-0.12.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gwbackupy 0.12.0
File Interpreter ABI Platform Actions
gwbackupy-0.12.0-py3-none-any.whl Python 3 none any Details for gwbackupy-0.12.0-py3-none-any.whl

Total release size: 72.5 kB

Release files / gwbackupy-0.12.0.tar.gz

Download URL gwbackupy-0.12.0.tar.gz
Size 32.9 kB
Tags Source
SHA-256 checksum
How to use checksums
36b7e6ddfd714e8907fc8b78f4d7a247f40413dc2349c0eda15e5e23e9d433a7
BLAKE2b-256 checksum
How to use checksums
bc3f62309998d113e105b46ad7e12dc5f3aeac5109a7a1fc15c4c75da1fa3c67
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

Release files / gwbackupy-0.12.0-py3-none-any.whl

Download URL gwbackupy-0.12.0-py3-none-any.whl
Size 39.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b4f6334da950c5d1fb657db9f17e4df0cf9e062f6cddb6683788855cedc5e281
BLAKE2b-256 checksum
How to use checksums
8b7ba27d53e61538298c3bf5d3e10db49957d628844b9060feeff16796ec77cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

Security for gwbackupy 0.12.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page