Flutter Desktop Updater

A pure Dart, cross-platform auto-update system for Flutter desktop applications.

pub package License: MIT

Features

✅ Pure Dart - No native code required
✅ Cross-platform - macOS, Windows, Linux
✅ Smart permissions - Handles macOS admin rights automatically
✅ Progress tracking - Real-time download progress
✅ User control - Users decide when to restart
✅ Clean UI - Non-intrusive banner notifications

Screenshots

Add screenshots here

Installation

Add to your pubspec.yaml:

dependencies:
  flutter_desktop_updater:
    git:
      url: https://github.com/qasimovv/flutter_desktop_updater.git
      ref: main

Or from pub.flutter-io.cn (once published):

dependencies:
  flutter_desktop_updater: ^0.0.5

Then run:

flutter pub get

Quick Start

1. Configure (once in main.dart)

import 'package:flutter/material.dart';
import 'package:flutter_desktop_updater/flutter_desktop_updater.dart';

void main() {
  // Configure your update server URL
  UpdateConfig().configure(
    updateJsonUrl: 'https://your-server.com/updates/app.json',
  );
  
  runApp(const MyApp());
}

2. Check for updates

class _MyHomePageState extends State<MyHomePage> {
  @override
  void initState() {
    super.initState();
    // Check for updates when app starts
    UpdateManager().checkForUpdate();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          // Show update banner at the top
          const UpdateBanner(),
          
          // Your app content
          Expanded(
            child: YourContent(),
          ),
        ],
      ),
    );
  }
}

3. Create your update JSON file

Host a JSON file on your server with this format:

{
  "macos": {
    "version": "1.0.1",
    "build_number": "2",
    "download_url": "https://your-server.com/MyApp-macos-1.0.1.zip",
    "file_size": 52428800,
    "release_notes": "Bug fixes and improvements"
  },
  "windows": {
    "version": "1.0.1",
    "build_number": "2",
    "download_url": "https://your-server.com/MyApp-windows-1.0.1.zip",
    "file_size": 48000000,
    "release_notes": "Bug fixes and improvements"
  },
  "linux": {
    "version": "1.0.1",
    "build_number": "2",
    "download_url": "https://your-server.com/MyApp-linux-1.0.1.zip",
    "file_size": 50000000,
    "release_notes": "Bug fixes and improvements"
  }
}

How It Works

  1. App checks for updates on startup
  2. If update is available, a banner appears at the top
  3. User clicks "Update" → Download starts with progress bar
  4. After download completes → "Quit & Restart" button appears
  5. User clicks button → App restarts with new version

Platform-Specific Notes

macOS

  • If app is in /Applications and owned by root, it will request password
  • Recommended: Install to ~/Applications for password-free updates
  • Supports both .app bundles

Windows

  • Works with portable .exe files
  • No admin rights needed if installed in user folder
  • Recommended: Use %LOCALAPPDATA% for installation

Linux

  • Supports both AppImage and binary formats
  • No sudo needed if in user folder
  • Recommended: Use ~/.local/bin or ~/Applications

API Reference

UpdateConfig

// Initialize (required, call once in main())
UpdateConfig().configure(
  updateJsonUrl: 'https://your-server.com/updates.json',
);

// Check if configured
bool isConfigured = UpdateConfig().isConfigured;

UpdateManager

// Get singleton instance
final manager = UpdateManager();

// Check for updates
await manager.checkForUpdate();

// Start update process
await manager.startUpdate();

// Restart app
await manager.restartApp();

// Dismiss update notification
manager.dismiss();

// Listen to status changes
manager.addListener(() {
  print('Status: ${manager.status}');
  print('Progress: ${manager.progress}');
  print('Error: ${manager.error}');
});

UpdateStatus

enum UpdateStatus {
  initial,          // No update check yet
  checking,         // Checking for updates
  updateAvailable,  // Update is available
  updating,         // Downloading and installing
  readyToRestart,   // Ready to restart
  error             // An error occurred
}

UpdateBanner

// Simple usage (recommended)
const UpdateBanner()

// The banner automatically:
// - Shows when update is available
// - Displays download progress
// - Shows restart button when ready
// - Handles errors

Example

See the example directory for a complete working example.

cd example
flutter run -d macos  # or windows, linux

Server Setup

Option 1: GitHub Releases (Free)

  1. Create a release on GitHub
  2. Upload your ZIP files
  3. Create app.json in your repo
  4. Use raw GitHub URL: https://rawgit.flutter-io.cn/user/repo/main/app.json

Option 2: Your Own Server

  1. Upload ZIP files to your server
  2. Create app.json with download URLs
  3. Enable CORS if needed
  4. Use HTTPS (recommended)

Option 3: CDN (CloudFlare, AWS S3, etc.)

  1. Upload files to CDN
  2. Create JSON file with CDN URLs
  3. Configure CDN settings

ZIP File Structure

Your ZIP file should contain:

macOS:

MyApp-macos.zip
└── MyApp.app/
    └── Contents/
        └── MacOS/
            └── MyApp

Windows:

MyApp-windows.zip
└── MyApp.exe

Linux:

MyApp-linux.zip
└── MyApp.AppImage  (or binary)

Troubleshooting

macOS: "App is damaged"

# Remove quarantine attribute
xattr -cr /Applications/MyApp.app

Windows: Antivirus blocking

  • Add exception to Windows Defender
  • Code sign your app (recommended)

Linux: Permission denied

# Make executable
chmod +x MyApp.AppImage

Contributing

Contributions are welcome! Please read our contributing guidelines first.

License

MIT License - see LICENSE file for details.

Support

Author

Your Name

Libraries

flutter_desktop_updater
Flutter Desktop Updater