GoFile Downloader (gofile-dl)

Note: This project began as a fork of rkwyu/gofile-dl but has since evolved into a completely rebuilt application with a different architecture and extensive new features.

A powerful, modern web application and CLI tool for downloading files and folders from GoFile.io links. Featuring a responsive web interface, task management, progress tracking, and Docker support.

Originally inspired by rkwyu/gofile-dl but completely rebuilt with extensive enhancements and a modern architecture.

Important Notes

GoFile API Compatibility (March 2026 Update)

BREAKING CHANGE: GoFile has restricted their API to premium accounts only as of March 2026.

This application has been updated to work around these restrictions:

• ✅ Automatic Fallback: When the API returns error-notPremium, the app automatically falls back to web scraping
• ✅ Browser Session Emulation: Uses browser-like requests to access content through the web interface
• ✅ Updated Authentication: Uses X-Website-Token header for API access
• ✅ Nested Folders: Full support for deeply nested folder structures with UUID-based IDs
• ✅ Special Characters: Properly handles emoji and special characters in folder names
• ✅ Password Protection: Supports SHA-256 password hashing for protected content
• ✅ Recursive Downloads: Automatically traverses and downloads all subfolders

Note: The GoFile API structure has changed significantly. The /contents/{id} endpoint now requires premium accounts. This version includes a web-based fallback mechanism to maintain functionality for free users.

Features

Core Functionality

• Download individual files or entire folder structures from GoFile.io links
• Full recursive support for nested subfolders (including UUID-based and short-form IDs)
• Password-protected content with SHA-256 hash authentication
• Smart folder handling with automatic emoji and special character sanitization
• CLI and web interface options
• Automatic retry on failed downloads with configurable attempts

Web Interface

• Modern, responsive design with Bootstrap 5
• Light/dark mode toggle with preference saving
• Interactive file system browser for selecting download locations
• Real-time download progress tracking with overall progress and ETA
• Task categorization and filtering by status and date
• Comprehensive dashboard with download statistics

Advanced Features

• Download speed limiting/throttling
• Configurable retry attempts for failed downloads
• Emoji stripping option for Linux CLI compatibility (removes emojis from folder/file names)
• Incremental/Sync mode - Only download new files, skip existing ones
  • Perfect for ongoing series with "NEW FILES in" folders
  • Automatically handles folder renames (e.g., "⭐NEW FILES in Show S1" → "Show S1")
  • Tracks downloaded files to avoid re-downloading
• Pause/resume downloads
• File size information display
• Task management (cancel, delete files, remove from list)
• Copy download links to clipboard
• Authentication for security

Deployment

• Docker and Docker Compose support
• Environment variable configuration
• Health check endpoint for container monitoring
• CSRF protection and security best practices

Quick Start

Using Docker (Recommended)

Docker Deployment Guide

GoFile Downloader is designed to run well in containers. This section provides comprehensive information on deploying with Docker.

Quick Start with Docker

# Build the Docker image
docker build -t gofile-dl:latest .

# Run with basic configuration
docker run -d --name gofile-dl \
  -p 2355:2355 \
  -v /your/download/path:/data \
  gofile-dl:latest

Docker Compose Deployment

Create a docker-compose.yml file:

version: "3.8"

services:
  gofile-dl:
    image: ghcr.io/martadams89/gofile-dl:latest
    container_name: gofile-dl
    ports:
      - "2355:2355"
    volumes:
      - ./downloads:/data
      - ./config:/config
    environment:
      - PORT=2355
      - HOST=0.0.0.0
      - BASE_DIR=/data
      - CONFIG_DIR=/config
      - SECRET_KEY=change-this-to-a-random-string-in-production
      # Uncomment to enable authentication
      # - AUTH_ENABLED=true
      # - AUTH_USERNAME=admin
      # - AUTH_PASSWORD=your-secure-password
      # Uncomment and add your GoFile premium token to bypass free account restrictions
      # - GOFILE_PREMIUM_TOKEN=your-premium-token-here
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:2355/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL

Run with:

docker-compose up -d

Environment Variables Reference

Variable	Description	Default	Example
PORT	Web server port	2355	8080
HOST	Web server host	0.0.0.0	127.0.0.1
BASE_DIR	Base directory for downloads	/app	/downloads
CONFIG_DIR	Directory for config/tracking	/config	/app/config
SECRET_KEY	Flask secret key for sessions	Random value	my-secret-key
DEBUG	Enable Flask debug mode	false	true
AUTH_ENABLED	Enable basic authentication	false	true
AUTH_USERNAME	Authentication username	admin	user
AUTH_PASSWORD	Authentication password	change-me-in-production	secure-password
DEFAULT_RETRIES	Default retry attempts	3	5
RETRY_DELAY	Seconds between retry attempts	5	10
GOFILE_PREMIUM_TOKEN	GoFile premium account token	None	your-token-here

Premium Account Support

If you have a GoFile premium account, you can use your account token to bypass free account restrictions:

Benefits of using a premium token:

• Bypasses error-notPremium API restrictions
• Faster and more reliable downloads
• No need for web scraping fallback
• Direct API access

How to use:

1. Find your token: Log into your GoFile account at gofile.io/myProfile and copy your account token

2. Configure via environment variable (Docker):

   environment:
     - GOFILE_PREMIUM_TOKEN=your-premium-token-here

3. Configure via config.yml (non-Docker):

   premium_token: "your-premium-token-here"

4. Or enter per-download in the web interface:

   • Click "Advanced Options" in the download form
   • Enter your token in the "GoFile Premium Account Token" field

Note: Tokens entered in the web UI override the config/environment variable for that specific download.

Docker Volumes

GoFile Downloader uses the following volumes:

• /data: Main storage location for downloaded files
• /config: Persistent storage for download tracking files (incremental mode)

Security Best Practices

For a secure deployment:

1. Use Authentication: Enable authentication by setting AUTH_ENABLED=true and setting a strong password
2. Set a Custom Secret Key: Provide a strong SECRET_KEY for sessions and CSRF protection
3. Limit Network Access: Consider running behind a reverse proxy with HTTPS
4. Use Non-Root User: The container already runs as non-root user gofile
5. Keep Updated: Regularly rebuild the container to get security updates

Advanced Docker Configurations

With HTTPS Reverse Proxy (Traefik Example)

version: "3.8"

services:
  gofile-dl:
    image: ghcr.io/martadams89/gofile-dl:latest
    volumes:
      - ./downloads:/data
      - ./config:/config
    environment:
      - AUTH_ENABLED=true
      - AUTH_USERNAME=admin
      - AUTH_PASSWORD=secure-password
      - CONFIG_DIR=/config
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.gofile.rule=Host(`gofile.example.com`)"
      - "traefik.http.routers.gofile.entrypoints=websecure"
      - "traefik.http.routers.gofile.tls.certresolver=letsencrypt"
    networks:
      - proxy
    restart: unless-stopped

networks:
  proxy:
    external: true

Resource-Limited Configuration

version: "3.8"

services:
  gofile-dl:
    image: ghcr.io/martadams89/gofile-dl:latest
    volumes:
      - ./downloads:/data
      - ./config:/config
    environment:
      - PORT=2355
      - CONFIG_DIR=/config
    deploy:
      resources:
        limits:
          cpus: "0.50"
          memory: 512M
        reservations:
          cpus: "0.25"
          memory: 128M
    restart: unless-stopped

Health Check and Monitoring

GoFile Downloader provides a health check endpoint at /health that returns system information and application status in JSON format. This can be used by container orchestration tools to monitor the application's health.

Example health check response:

{
  "status": "ok",
  "timestamp": 1651234567.89,
  "system": {
    "system": "Linux",
    "python_version": "3.11.0",
    "cpu_usage": 5.2,
    "memory": {
      "total": 8589934592,
      "available": 4294967296,
      "percent": 50.0
    },
    "disk": {
      "total": 107374182400,
      "free": 53687091200,
      "percent": 50.0
    }
  },
  "application": {
    "status": "healthy",
    "active_tasks": 2,
    "version": "2.0.0"
  }
}

Troubleshooting Docker Deployment

1. Container fails to start

   • Check logs: docker logs gofile-dl
   • Verify environment variables are correctly set
   • Ensure the download directory has correct permissions

2. Cannot access web interface

   • Confirm port mapping: docker ps
   • Check if the host firewall allows access to the port
   • Verify the container is running: docker ps | grep gofile-dl

3. Download files not appearing

   • Check the volume mounting: docker inspect gofile-dl
   • Verify the BASE_DIR environment variable is set correctly
   • Check directory permissions
   • Permission denied errors: Ensure the mounted directory is writable by UID 1000 (default container user)

4. Authentication issues

   • Ensure AUTH_ENABLED is set to "true" (case-sensitive)
   • Verify username and password are correctly set
   • Clear browser cache and cookies

5. GoFile download errors

   • Error "Cannot get wt": GoFile may have updated their JavaScript structure. Check for application updates.
   • Error "API error: error-notPremium": This is expected as of March 2026. GoFile now restricts the API to premium accounts. The application automatically falls back to a web-based method to retrieve content. If you see this error followed by "Successfully retrieved content via web fallback", everything is working correctly.
   • Timeout errors (Read timed out): GoFile's API may be slow or overloaded. The app now uses 30-45 second timeouts and automatically retries 3 times. If timeouts persist, wait a few minutes and try again.
   • If web fallback fails: This may indicate GoFile has further changed their interface. Please check for updates or report the issue on GitHub.
   • Nested folders not downloading: Verify you're providing the top-level folder URL, not individual file links
   • Special characters in filenames: These are automatically sanitized - check the downloads folder for the converted names
   • Rate limiting: GoFile may rate limit API requests. Wait a few minutes and try again.

Testing

Running Tests

A test script is provided to verify GoFile connectivity:

# Test with environment variables
export GOFILE_TEST_URL="https://gofile.io/d/YOUR_CONTENT_ID"
export GOFILE_TEST_PASSWORD="your_password"  # Optional, only if content is password-protected
python test_gofile_api.py

# Or test directly with arguments
python test_gofile_api.py --url "https://gofile.io/d/YOUR_CONTENT_ID" --password "your_password"

The test script verifies:

• Token acquisition from GoFile API
• WebsiteToken (wt) extraction from config.js
• Content access with proper authentication
• Nested folder structure retrieval

Use Case: Tracking Ongoing Series with Incremental Mode

The incremental/sync mode is perfect for content that updates regularly, such as TV series, podcast archives, or any collection that receives periodic updates.

Why Use Incremental Mode?

When downloading from ongoing series or regularly updated folders:

• Avoid re-downloading files you already have
• Save bandwidth and time
• Keep your local copy synchronized with the remote folder
• Handle folder renames automatically (common with "NEW FILES" prefixes)

How It Works

1. Initial Download: Download the entire folder structure

   • Enable "Incremental/Sync mode" checkbox in the web UI
   • Or use incremental=true via API/curl

2. Subsequent Updates: Run the same download again

   • Only NEW files are downloaded
   • Previously downloaded files are automatically skipped
   • Handles folder renames with customizable pattern matching
   • Default patterns strip: ⭐NEW FILES in, NEW FILES in, ⭐

3. Behind the Scenes:

   • Creates persistent tracking file: .gofile_tracker_<contentId>.json in /config
   • Stores list of downloaded file IDs and names
   • Matches folders even when renamed using pattern normalization
   • Logs all skipped files for visibility

Customizing Folder Patterns

Different uploaders use different naming conventions. You can customize the patterns to match your specific use case:

1. Via Web UI:

   • Click "Advanced Options" to reveal pattern configuration
   • Enter pipe-separated patterns: ⭐NEW FILES in |NEW FILES in |⭐

2. Via API/curl:

   curl -X POST http://localhost:2355/start \
     -d "url=https://gofile.io/d/abc123" \
     -d "incremental=true" \
     -d "folder_pattern=UPDATED |⭐NEW |*NEW FILES in "

3. Pattern Examples:

   • ⭐NEW FILES in |NEW FILES in |⭐ (default) matches:
     • ⭐NEW FILES in Show S1 [10] → Show S1 [10]
     • NEW FILES in Episode Pack → Episode Pack
   • UPDATED |⭐NEW |*NEW FILES in matches:
     • UPDATED Show S1 → Show S1
     • ⭐NEW Episode Pack → Episode Pack
     • *NEW FILES in Series → Series

Example Workflow

# Week 1: Initial download - gets everything
docker-compose exec gofile-dl curl -X POST http://localhost:2355/start \
  -d "url=https://gofile.io/d/abc123" \
  -d "incremental=true" \
  -d "folder_pattern=⭐NEW FILES in |NEW FILES in |⭐"

# Week 2: Update download - only new episodes
# Same command - automatically skips existing files!
docker-compose exec gofile-dl curl -X POST http://localhost:2355/start \
  -d "url=https://gofile.io/d/abc123" \
  -d "incremental=true" \
  -d "folder_pattern=⭐NEW FILES in |NEW FILES in |⭐"

Configuration Notes

• Tracking files are stored in /config directory - ensure this volume is mounted in your docker-compose.yml
• Delete the tracking file .gofile_tracker_<contentId>.json to force a complete re-download
• The tracking is per content ID, so different GoFile folders are tracked separately
• Progress shown in the UI is per-subfolder, allowing you to see which folder is currently being processed

License

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

Contributing

Contributions are welcome! Here's how you can help:

1. Report bugs: Open an issue describing the bug and how to reproduce it
2. Suggest features: Open an issue describing the feature and its benefits
3. Submit pull requests: Fork the repository and submit a PR with your changes

Please ensure your code follows existing style conventions and includes appropriate tests.

Development Setup

# Clone the repository
git clone https://github.com/yourusername/gofile-dl.git
cd gofile-dl

# Install dependencies for development
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run tests
pytest

# Lint your code
flake8 .
black .

Support

Having issues with gofile-dl? Here are some resources:

• GitHub Issues: Use our issue tracker for bug reports and feature requests.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Acknowledgements

• Original concept by rkwyu/gofile-dl.
• Built with Flask and Bootstrap.
• Icons from Bootstrap Icons.
• Thanks to all contributors who have helped this project evolve!