WinRA: A Modern Native Archive Manager for macOS with CustomTkinter GUI

1. Introduction

Archive management on macOS has historically been limited compared to the Windows ecosystem. While Windows users have long relied on tools like WinRAR, 7-Zip, and WinZip for comprehensive archive handling, macOS provides only basic ZIP extraction through the built-in Archive Utility. Users who need RAR support, format conversion, or detailed archive inspection must resort to command-line tools or third-party applications that often feel foreign to the macOS environment.

WinRA addresses this gap by providing a native-feeling macOS application that combines the core functionality of WinRAR—extraction, compression, and format conversion—with a modern GUI that respects Apple's design language. The application is built entirely in Python using CustomTkinter, a modern widget library that extends Tkinter with contemporary styling capabilities including rounded corners, smooth transitions, and system-aware theming.

The key contributions of this work are:

• A complete archive management solution for macOS supporting both ZIP and RAR formats with extract, compress, and convert operations.
• A native-feeling macOS GUI built with CustomTkinter featuring automatic dark/light mode detection, SF Pro typography, and Apple-style color palettes.
• A threaded architecture that maintains UI responsiveness during long-running archive operations with real-time progress tracking.
• A comprehensive build pipeline producing .app, .dmg, and .pkg distribution artifacts from a single script.

2. Related Work

The archive management landscape on macOS is dominated by a handful of tools. The built-in Archive Utility handles ZIP creation and extraction but offers no GUI for archive inspection, no RAR support, and no format conversion. The Unarchiver (codename: unar) provides broad format support via command-line tools but lacks a modern GUI. Keka offers a native macOS interface but is primarily focused on compression rather than archive inspection or conversion.

On the GUI framework side, CustomTkinter (Schimansky, 2022) has emerged as a popular choice for building modern-looking desktop applications in Python. Unlike traditional Tkinter, which produces dated-looking interfaces, CustomTkinter provides rounded widgets, system-aware theming, and a flat design aesthetic that aligns with contemporary macOS design. Alternative frameworks like PyQt and wxPython offer more comprehensive widget sets but introduce significant dependency overhead and licensing considerations.

WinRA combines the format breadth of unar with the modern GUI capabilities of CustomTkinter, resulting in an application that feels native to macOS while providing the comprehensive archive management functionality previously available only on Windows through tools like WinRAR.

3. System Architecture

WinRA follows a clean Model-View-Controller architecture with three dedicated Python modules: gui.py for the user interface, archive_ops.py for archive operations, and utils.py for utility functions. This separation ensures that archive logic remains independent of the GUI layer, facilitating testing and maintenance.

3.1 Application Structure

WinRA/
  main.py              # Application entry point
  requirements.txt     # Python dependencies
  build.sh             # Build script (.app, .dmg, .pkg)
  build_pkg.sh         # PKG installer builder
  app/
    __init__.py
    gui.py             # Main GUI (CustomTkinter) — 1,141 lines
    archive_ops.py     # Archive operations (extract, compress, convert)
    utils.py           # Utility functions (path handling, format detection)

3.2 Operation Flow

All three core operations follow a consistent pattern:

The critical design decision is the use of threading.Thread with daemon=True for all archive operations. This ensures the GUI remains responsive during long-running extractions or compressions. Progress updates are marshaled back to the main thread using Tkinter's self.after(0, callback) mechanism, which schedules UI updates on the next event loop iteration.

4. GUI Design

WinRA's interface is designed to feel native to macOS, drawing from Apple's Human Interface Guidelines while adapting them to CustomTkinter's widget capabilities.

4.1 macOS Color System

The application implements a comprehensive dual-mode color system through the MacColors class, which defines both system accent colors (Blue #007AFF, Green #34C759, Purple #AF52DE, Red #FF3B30) and complete light/dark palettes covering backgrounds, text hierarchy, separators, cards, toolbar, inputs, and tags. The initial mode is detected at startup using the darkdetect library, which reads macOS system preferences.

4.2 Layout Architecture

The main window (1060×680px, minimum 900×580px) uses a two-column grid layout:

• Left sidebar (220px fixed): Contains the application branding (blue icon badge + title), a "TOOLS" section label, three navigation buttons (Extract Archive, Compress Files, Convert Format), a dark/light mode toggle switch, and the version string.
• Right main area (flexible): Comprises a toolbar with mode title and contextual action buttons, an action card with drop zone, file information display, and primary action button, an output path bar with "Show in Finder" integration, a Treeview-based file content inspector, and a progress bar with status label.

4.3 Tab-Based Navigation

The three operational modes are implemented as soft tabs controlled by sidebar buttons. Each tab configures the UI with mode-specific labels, button colors, toolbar actions, and empty-state messages. The active tab receives a blue highlight (#007AFF) while inactive tabs use transparent backgrounds with hover effects:

4.4 Theme Toggle

The dark/light mode switch triggers a comprehensive theme update that refreshes over 25 UI elements including the sidebar, navigation buttons, toolbar, action cards, drop zone, file info labels, output bar, tree card, progress bar, and ttk Treeview styles. This is necessary because CustomTkinter's set_appearance_mode() does not automatically propagate to all custom-configured widgets.

5. Archive Operations

5.1 ZIP Handling

ZIP operations use Python's built-in zipfile module with ZIP_DEFLATED compression. Extraction iterates over archive members with per-file progress callbacks, while compression supports both individual files and recursive directory walking with relative path preservation. The get_archive_info() function parses ZIP metadata including per-file sizes, compressed sizes, and directory flags.

5.2 RAR Handling

RAR operations delegate to the unar and lsar command-line tools from The Unarchiver project (installable via brew install unar). The lsar -j command provides JSON-formatted archive listings for the content inspector, while unar -o <dest> -f performs extraction. A file-snapshotting approach is used for progress tracking: the destination directory is scanned before and after extraction, with only newly created files counted as extracted.

Tool discovery uses a cascading search strategy: shutil.which() for PATH-based lookup, followed by checks at /opt/homebrew/bin/ (Apple Silicon), /usr/local/bin/ (Intel Homebrew), and /usr/bin/ (system).

5.3 Format Conversion

Conversion between RAR and ZIP formats is implemented as a two-phase pipeline using a temporary directory:

RAR-to-ZIP conversion extracts via unar and re-compresses with zipfile. ZIP-to-RAR conversion requires the rar command-line tool, which is noted as optional since WinRAR CLI is a proprietary tool. Progress callbacks report approximate percentages (0–50% for extraction, 50–100% for re-compression).

6. Archive Content Inspector

The Treeview-based content inspector displays four columns: Name (with file-type emoji icons), Size (human-readable), Packed (compressed size), and Kind (file extension). The icon mapping covers 30+ file types including documents, images, audio, video, code files, and archives. The inspector uses ttk Treeview with custom styling to match the macOS aesthetic, including selection highlighting in system blue and header styling consistent with the application's color system.

7. Build and Distribution

The build.sh script produces three distribution artifacts from a single invocation:

7.1 Build Pipeline

PyInstaller bundles the application with --windowed (no terminal window) and --onedir (directory bundle), collecting all CustomTkinter resources and hidden imports (PIL, rarfile, darkdetect). The DMG is created using macOS's native hdiutil with UDZO compression and includes a symbolic link to /Applications for drag-and-drop installation. Ad-hoc code signing with codesign -s - removes quarantine attributes that would otherwise trigger Gatekeeper warnings.

7.2 Dependencies

8. System Requirements

9. Conclusion and Future Work

WinRA demonstrates that Python with CustomTkinter is a viable platform for building native-feeling macOS desktop applications. The combination of CustomTkinter's modern widget styling, darkdetect's system theme integration, and SF Pro typography produces an interface that is visually consistent with native macOS applications while maintaining the rapid development velocity that Python provides.

The threaded architecture ensures UI responsiveness during resource-intensive archive operations, and the clean MVC separation between GUI, operations, and utilities facilitates maintainability. The single-script build pipeline producing .app, .dmg, and .pkg artifacts simplifies distribution to end users.

Future directions include:

• Support for additional archive formats (7z, tar.gz, tar.bz2, tar.xz) through integration with py7zr and Python's tarfile module.
• Drag-and-drop file input using Tkinter DnD extensions or platform-specific APIs.
• Archive encryption support with AES-256 for creating password-protected ZIP files.
• Batch operations for processing multiple archives simultaneously.
• Integration with macOS Quick Look for archive preview without opening the full application.
• Apple Notarization for distribution outside the Mac App Store without Gatekeeper warnings.

The complete source code is available at https://github.com/romizone/WinRA under the MIT license.

References