Polaroid is a powerful Python script manager for macOS that transforms how you organize, run, and maintain your Python automation scripts. Think of it as iTunes for your Python scripts - a beautiful, native Mac app that makes script management effortless.
If you're like most developers, you probably have:
- 📁 Python scripts scattered across different folders
- 🤷 No easy way to remember what arguments each script needs
- 😤 Manual virtual environment management for each script
- 📝 No centralized way to track which scripts do what
- ⏰ Cron jobs or LaunchAgents that are hard to manage
- 🔍 Difficulty finding that one script you wrote months ago
Polaroid brings order to this chaos by providing:
- A Central Library - All your scripts in one beautiful interface
- Smart Organization - Collections, tags, and smart folders to organize scripts
- Automatic Setup - Virtual environments and dependencies handled automatically
- Visual Arguments - No more remembering command-line flags
- Scheduling - Schedule scripts to run automatically with a visual interface
- Health Monitoring - Know when scripts break or need attention
- 🧑💻 Developers who write automation scripts for various tasks
- 📊 Data Scientists managing data processing and analysis scripts
- 🔧 System Administrators maintaining system automation scripts
- 🎨 Creative Professionals using Python for content generation or processing
- 📈 Business Analysts running regular reports and data exports
- 🏫 Educators & Students organizing learning projects and assignments
- Data Processing - Schedule daily data cleanup and transformation scripts
- Web Scraping - Manage and run web scrapers with visual scheduling
- System Maintenance - Organize backup scripts, cleanup utilities, and monitoring tools
- API Integrations - Manage scripts that sync data between services
- Report Generation - Schedule and run automated reporting scripts
- Development Tools - Quick access to build scripts, deployment tools, and utilities
Polaroid automatically analyzes your Python scripts when you import them:
- Automatic Argument Detection - Detects argparse arguments and creates a visual form
- Dependency Discovery - Finds and installs required packages from requirements.txt
- Multi-file Support - Import entire projects from ZIP files
- Metadata Extraction - Pulls description, version, and author from your script
No more terminal commands to remember:
- Visual Argument Forms - Fill in script arguments through a clean UI
- Saved Configurations - Save and reuse common argument combinations
- Real-time Output - Watch your script run with colored terminal output
- Error Handling - Clear error messages with suggested fixes
Keep your scripts organized effortlessly:
- Custom Collections - Create folders with custom names, icons, and colors
- Smart Collections - Auto-organizing folders based on rules you define
- Drag & Drop - Simply drag scripts to collections to organize them
- Tags - Add tags to scripts for easy categorization
- Full-Text Search - Find scripts by name, description, or even code content
Schedule scripts without touching cron or LaunchAgents:
- Visual Scheduler - Set up schedules with a visual interface
- Multiple Modes:
- Interval: Run every X minutes/hours/days
- Calendar: Run at specific times on specific days
- Startup: Run when your Mac starts
- LaunchAgent Integration - Creates proper macOS LaunchAgents behind the scenes
- Schedule Management - View, edit, and disable schedules from one place
Know the status of your scripts at a glance:
- Status Indicators - Green (healthy), Yellow (warning), Red (error)
- Dependency Checking - Ensures required packages are installed
- Execution Tracking - See success/failure rates over time
- Issue Detection - Automatically detects common problems
- Manual Override - Mark scripts as healthy when you've fixed external issues
Never worry about Python environments again:
- Automatic Creation - Each script gets its own virtual environment
- Isolated Dependencies - No more version conflicts between scripts
- Transparent Management - Polaroid handles activation/deactivation
- Update Support - Easy dependency updates through the UI
- 🍎 macOS 14.0 (Sonoma) or later
- 🐍 Python 3.9+ installed on your system
- 💻 Xcode 15.0+ (for building from source)
- 📦 XcodeGen (
brew install xcodegen)
- Go to Releases
- Download the latest
Polaroid.app.zip - Unzip and drag to your Applications folder
- Open Polaroid from Applications
# Clone the repository
git clone https://github.com/yitsf/Polaroid.git
cd Polaroid
# Build the app
python3 compile.py --clean --install
# The app will be installed to /Applications- Launch Polaroid from your Applications folder
- Import Your First Script:
- Click the "+" button or drag a Python file into the app
- Polaroid will analyze and set up the script automatically
- Run Your Script:
- Select it from the library
- Fill in any arguments in the form
- Click "Run" to execute
When you import a script, Polaroid creates a "package" for it:
~/.polaroid/packages/my-script.polaroid/
├── polaroid.json # Script metadata and configuration
├── requirements.txt # Python dependencies
├── src/ # Your script files
│ └── main.py
├── .venv/ # Isolated virtual environment
└── logs/ # Execution logs
Polaroid automatically detects arguments from your script's argparse configuration:
# Your script
parser = argparse.ArgumentParser(description='Process some files')
parser.add_argument('input_file', help='Input file path')
parser.add_argument('--output', '-o', default='output.txt', help='Output file')
parser.add_argument('--verbose', '-v', action='store_true', help='Verbose output')This automatically creates a form in Polaroid with:
- A required field for
input_file - An optional field for
outputwith default value - A checkbox for
verbosemode
Polaroid uses macOS's native LaunchAgent system for scheduling:
- Creates proper plist files in
~/Library/LaunchAgents/ - Manages agent lifecycle (load/unload)
- Provides visual interface for complex schedules
- No need to understand LaunchAgent syntax
Create dynamic collections that auto-update based on rules:
- By Status: "All failing scripts"
- By Usage: "Scripts run in the last week"
- By Type: "All data processing scripts" (using tags)
- By Performance: "Scripts that take > 5 minutes"
- Custom Rules: Combine multiple conditions with AND/OR logic
Full support for interactive Python scripts:
- NCurses/Terminal UI - Scripts with terminal interfaces work perfectly
- Input Support - Scripts that need user input are supported
- Color Output - Full ANSI color support in the console
- Progress Bars - Terminal progress indicators display correctly
Share scripts and collections easily:
- Export Scripts - Bundle scripts with their dependencies
- Export Collections - Share entire collections as bundles
- Import Bundles - One-click import of shared bundles
- Preserve Relationships - Maintains collection membership and metadata
Power user features for efficiency:
⌘N- Import new script⌘R- Run selected script⌘,- Open preferences⌘F- Search scripts⌘1/2/3- Switch between tabs in detail view
- SwiftUI - Native macOS user interface
- SwiftData - Apple's modern persistence framework
- Combine - Reactive programming for real-time updates
- Process/NSTask - Secure script execution
- XPC Services - Sandboxed script running (planned)
- Scripts run in isolated virtual environments
- No network access without explicit permission
- All data stored locally in
~/.polaroid/ - No telemetry or data collection
Comprehensive guides available in the docs directory:
- Quick Start Guide - Get up and running quickly
- Build Guide - Detailed build instructions for developers
- Argument Editing Guide - Advanced argument management
- Script Templates - Start from pre-built templates
- Performance Analytics - Detailed execution metrics and charts
- Cloud Sync - Sync scripts across devices (optional)
- Script Marketplace - Share and discover community scripts
- Multiple Language Support - Ruby, Node.js, Shell scripts
- API Access - REST API for automation
- iOS Companion App - Monitor and trigger scripts from your iPhone
- Git integration for version control
- Collaborative script sharing within teams
- AI-powered script generation and optimization
- Docker container support
- Remote execution on servers
We welcome contributions! See CONTRIBUTING.md for guidelines.
- 🐛 Report bugs and issues
- 💡 Suggest new features
- 📝 Improve documentation
- 🌍 Add localizations
- 🧪 Write tests
- 💻 Submit pull requests
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Wiki: Documentation Wiki
- Author: @yitsf
- Twitter: @yitsf
- Email: support@polaroid.app
This project is licensed under the MIT License - see the LICENSE file for details.
- SwiftUI - Apple's modern UI framework
- SwiftData - Apple's persistence framework
- XcodeGen - Project generation
- SF Symbols - Beautiful system icons
- The macOS developer community
- Contributors and testers
- Everyone who has provided feedback
Made with 💜 for the macOS community
Your home for lost scripts
Download Latest Release | Report an Issue | Request a Feature