A powerful, modular Python tool to automatically back up your Notion workspace with pluggable storage backends and notification systems.

• 🚀 Export entire Notion workspace - Complete backup of all your data
• 📦 Pluggable storage backends - Local, rclone (cloud storage), with more coming
• 📧 Rich notifications - Apprise integration for 70+ notification services
• 🔧 Highly configurable - Customize every aspect via environment variables
• 📝 Detailed logging - Comprehensive logging for debugging and monitoring
• 🔒 Secure - Token-based authentication with Notion
• ⚡ Async/await support - Fast, concurrent operations
• 🧹 Automatic cleanup - Keep only the most recent backups
• 📊 Multiple export formats - Markdown or HTML output
• 🔄 Retry logic - Robust error handling with exponential backoff
• 📬 Smart notification management - Automatically mark export notifications as read
• 🔄 Export Recovery - Optional Redis integration to recover from rare Notion notification failures

The tool is built with a modular, pluggable architecture:

src/notion_backup/
├── core/           # Core backup logic
│   ├── client.py   # Notion API client
│   └── backup.py   # Main backup orchestrator
├── storage/        # Storage backends
│   ├── local.py    # Local file storage
│   └── rclone.py   # Rclone cloud storage
├── notifiers/      # Notification backends
│   └── apprise.py  # Apprise notifications
├── config/         # Configuration management
└── utils/          # Utility functions
    └── redis_client.py # Optional Redis client for export recovery

# Clone the repository
git clone https://github.com/nikhilbadyal/notion.git
cd notion-backup

# Install dependencies
pip install -r requirements.txt

Copy the example environment file:

cp .env.example .env

1. Login to Notion
2. Open browser developer console → Network tab
3. Use "Quick Find" and search for something
4. Find the search request and copy:
   • spaceId → NOTION_SPACE_ID
   • token_v2 cookie → NOTION_TOKEN_V2
   • file_token cookie → NOTION_FILE_TOKEN

Edit your .env file with your credentials:

# Required
NOTION_SPACE_ID=your_actual_space_id_here
NOTION_TOKEN_V2=your_actual_token_v2_here
NOTION_FILE_TOKEN=your_file_token

# Optional - defaults shown
STORAGE_BACKEND=local
EXPORT_TYPE=markdown
LOCAL_PATH=./downloads

# Simple backup
python main.py backup

# With debug logging
python main.py --debug backup

# List available backups
python main.py list

# Cleanup old backups (keep 5 most recent)
python main.py cleanup --keep 5

This project is fully containerized, allowing you to run the backup tool in a consistent and isolated environment.

• Docker
• Docker Compose

1. Configure Environment: Create a .env file by copying the .env.example and filling in your Notion credentials and other settings.

2. Build and Run: Use docker-compose to build the image and run the backup service.

   # Build the Docker image
   docker-compose build
   
   # Run a one-off backup
   docker-compose run --rm notion-backup

To run backups on a schedule, you can use a standard cron job on your host machine to execute the docker-compose run command.

Example Cron Job (daily at 2 AM):

0 2 * * * cd /path/to/notion-backup && /usr/local/bin/docker-compose run --rm notion-backup

Store backups on local filesystem:

STORAGE_BACKEND=local
LOCAL_PATH=./downloads
MAX_BACKUPS=10

Store backups on any cloud provider supported by rclone:

STORAGE_BACKEND=rclone
RCLONE_REMOTE=mycloud
RCLONE_PATH=notion-backups
RCLONE_CONFIG_PATH=/path/to/rclone.conf
KEEP_LOCAL_BACKUP=true

Get notified about backup status via 70+ services using Apprise:

ENABLE_NOTIFICATIONS=true
NOTIFICATION_LEVEL=all
APPRISE_URLS=discord://webhook_id/webhook_token,mailto://user:pass@smtp.gmail.com?to=you@gmail.com

Popular notification services:

• Discord: discord://webhook_id/webhook_token
• Slack: slack://TokenA/TokenB/TokenC/Channel
• Email: mailto://user:pass@domain.com?to=recipient@domain.com
• Telegram: tgram://bottoken/ChatID
• Microsoft Teams: msteams://TokenA/TokenB/TokenC/
• PushBullet: pbul://accesstoken

See full list of supported services

This feature uses Redis to recover from rare cases where a Notion export succeeds but the completion notification isn't received. When enabled, failed notifications are queued in Redis and processed on subsequent backup runs.

Note: Redis is completely optional. If REDIS_HOST is not set, the feature is disabled and backups proceed normally. Install Redis via your package manager or Docker for production use. For TLS-enabled Redis servers (common in cloud providers), set REDIS_SSL=true and provide certificate details if required.

# Run backup (default command)
python main.py
python main.py backup

# List available backups
python main.py list

# Clean up old backups
python main.py cleanup --keep 5

# Test configuration
python main.py test

# Enable debug logging
python main.py --debug backup

1. Create a new class inheriting from AbstractStorage
2. Implement required methods: store, list_backups, cleanup_old_backups, test_connection
3. Register in BackupManager._create_storage_backend()

1. Create a new class inheriting from AbstractNotifier
2. Implement required methods: send_notification, test_connection
3. Register in BackupManager._create_notifier()

# .env
NOTION_SPACE_ID=your_space_id
NOTION_TOKEN_V2=your_token
NOTION_FILE_TOKEN=your_file_token

STORAGE_BACKEND=local
LOCAL_PATH=./backups
MAX_BACKUPS=7

ENABLE_NOTIFICATIONS=true
APPRISE_URLS=mailto://user:pass@gmail.com?to=you@gmail.com
MARK_NOTIFICATIONS_AS_READ=true

# .env
NOTION_SPACE_ID=your_space_id
NOTION_TOKEN_V2=your_token
NOTION_FILE_TOKEN=your_file_token

STORAGE_BACKEND=rclone
RCLONE_REMOTE=gdrive
RCLONE_PATH=backups/notion
KEEP_LOCAL_BACKUP=false

ENABLE_NOTIFICATIONS=true
APPRISE_URLS=discord://webhook_id/webhook_token
NOTIFICATION_LEVEL=all

# .env
NOTION_SPACE_ID=your_space_id
NOTION_TOKEN_V2=your_token
NOTION_FILE_TOKEN=your_file_token

STORAGE_BACKEND=rclone
RCLONE_REMOTE=s3backup
RCLONE_PATH=company-notion-backups
RCLONE_ADDITIONAL_ARGS=--transfers=8,--checkers=16

ENABLE_NOTIFICATIONS=true
APPRISE_URLS=slack://TokenA/TokenB/TokenC/general,mailto://backup@company.com?to=it@company.com
NOTIFICATION_LEVEL=all

MAX_RETRIES=5
RETRY_DELAY=10

# Daily backup at 2 AM
0 2 * * * cd /path/to/notion-backup && python main.py backup

# Weekly cleanup (keep 30 backups)
0 3 * * 0 cd /path/to/notion-backup && python main.py cleanup --keep 30

Create a task that runs:

Program: python
Arguments: /path/to/notion-backup/main.py backup
Start in: /path/to/notion-backup

• Ensure all required environment variables are set
• Check .env file syntax

• For local: Check directory permissions
• For rclone: Test rclone config with rclone lsd remote:

• Token may have expired - get new tokens from browser
• Check network connectivity
• Verify space ID is correct

• Test notification URLs independently
• Check URL format in Apprise documentation

Enable debug logging for detailed troubleshooting:

python main.py --debug backup

# Test all connections
python main.py test

# Test specific components
python -c "from src.notion_backup.config import Settings; s=Settings(); print('Config loaded successfully')"

• Store .env file securely, never commit to version control
• NOTION_TOKEN_V2 provides full workspace access
• Tokens expire after ~1 year or on logout
• Use environment variables in production instead of .env files
• Regularly rotate tokens and review access

This project is licensed under the MIT License - see the LICENSE file for details.

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request