https://github.com/macadmins/icongrabber
A fast, lightweight command-line tool to extract high-quality icons from macOS applications
https://github.com/macadmins/icongrabber
Last synced: 5 months ago
JSON representation
A fast, lightweight command-line tool to extract high-quality icons from macOS applications
- Host: GitHub
- URL: https://github.com/macadmins/icongrabber
- Owner: macadmins
- License: apache-2.0
- Created: 2025-12-02T13:23:46.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-01-14T17:31:09.000Z (5 months ago)
- Last Synced: 2026-01-14T21:34:32.488Z (5 months ago)
- Language: Swift
- Homepage:
- Size: 145 KB
- Stars: 31
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Icon Grabber
**A fast, simple command-line tool to extract high-quality icons from macOS applications.**
[](LICENSE)
[](https://www.apple.com/macos/)
[](https://swift.org)
[](https://github.com/macadmins/icongrabber/actions)
---
**Found this tool helpful?** Consider [sponsoring the project](https://github.com/sponsors/macadmins) to support ongoing development and maintenance. Your support helps keep Icon Grabber free and open source for everyone!
[](https://github.com/sponsors/macadmins)
## Requirements
- **macOS 15 (Sequoia) or later**
## Features
- **Simple & Fast** - Extract icons with a single command
- **Flexible Sizing** - Get icons in any size from 16x16 to 1024x1024
- **High Quality** - Preserves original icon quality in PNG format
- **File Size Optimization** - Limit output file size using sips compression
- **Scriptable** - Perfect for automation and batch processing
- **Native** - Written in Swift, lightweight, no dependencies
## Installation
### Download Release (Recommended)
Download the latest installer from [Releases](https://github.com/macadmins/icongrabber/releases):
```bash
# Download the latest PKG installer
curl -LO $(curl -s https://api.github.com/repos/macadmins/icongrabber/releases/latest | grep "browser_download_url.*\.pkg" | cut -d '"' -f 4)
# Or if you know the latest version number, use:
# curl -LO https://github.com/macadmins/icongrabber/releases/latest/download/icongrabber-VERSION.pkg
# Install
sudo installer -pkg icongrabber-*.pkg -target /
# Verify installation
icongrabber --version
```
### Build from Source
```bash
# Clone the repository
git clone https://github.com/kitzy/icongrabber.git
cd icongrabber
# Build and install system-wide
make build
sudo make install
# Or install to your home directory (no sudo required)
make build
make install PREFIX=$HOME/.local
export PATH="$HOME/.local/bin:$PATH" # Add to ~/.zshrc
```
## Quick Start
Extract an icon in less than 30 seconds:
```bash
# Extract Safari's icon (creates Safari.png)
icongrabber /Applications/Safari.app
# Custom size
icongrabber /Applications/Safari.app -s 256
# Custom output location
icongrabber /Applications/Safari.app -o ~/Desktop/my-icon.png
# Limit file size to 100KB
icongrabber /Applications/Safari.app -m 100KB
# Limit file size to 2MB
icongrabber /Applications/Safari.app -m 2M
# Force overwrite existing file
icongrabber /Applications/Safari.app -f
```
That's it!
## Usage
### Basic Usage
```bash
icongrabber [options]
```
### Options
| Option | Description | Example |
|--------|-------------|---------|
| `-s, --size ` | Icon size (default: 512) | `-s 256` |
| `-o, --output ` | Output file path | `-o icon.png` |
| `-i, --input ` | Input app path (alternative) | `-i /Applications/Safari.app` |
| `-m, --max-file-size ` | Max file size (optimizes with sips) | `-m 100KB` or `-m 2M` |
| `-f, --force` | Overwrite existing files without prompting | `-f` |
| `-h, --help` | Show help message | `-h` |
| `-v, --version` | Show version | `-v` |
### Common Sizes
- **16x16** - Toolbar icons, favicons
- **32x32** - Small UI elements
- **64x64** - List views, thumbnails
- **128x128** - Standard app icons
- **256x256** - Retina displays
- **512x512** - High-resolution (default)
- **1024x1024** - Maximum quality
## Examples
### Extract a Single Icon
```bash
# Get Safari's icon at 512x512
icongrabber /Applications/Safari.app
```
### Specify Output Location
```bash
# Save to a specific location
icongrabber /Applications/Safari.app -o ~/Desktop/safari-icon.png
```
### Custom Size
```bash
# Get a 256x256 icon
icongrabber /Applications/Safari.app -s 256 -o small-icon.png
```
### Optimize File Size
```bash
# Extract icon and limit file size to 100KB (auto-selects 256x256)
icongrabber /Applications/Safari.app -m 100KB
# Limit to 2MB using shorthand (auto-selects 1024x1024)
icongrabber /Applications/Safari.app -m 2M
# Combine with custom size for better optimization (manual size selection)
icongrabber /Applications/Safari.app -s 256 -m 50K -o optimized.png
```
### Multiple Sizes
```bash
# Extract multiple sizes for the same app
./examples/extract_multiple_sizes.sh /Applications/Safari.app
```
### Batch Processing
```bash
# Extract icons from all applications
./examples/batch_extract.sh
```
### Automation Script
```bash
#!/bin/bash
# Extract icon and use it in your workflow
if icongrabber /Applications/MyApp.app -o assets/icon.png -s 512; then
echo "✓ Icon extracted successfully"
# Do something with the icon
convert assets/icon.png -resize 64x64 assets/icon-small.png
fi
```
## Output
### Default Naming
Icons are automatically named based on the app name (spaces removed):
| Application | Output File |
|-------------|-------------|
| Safari.app | `Safari.png` |
| Visual Studio Code.app | `VisualStudioCode.png` |
| Calculator.app | `Calculator.png` |
### Custom Naming
Use `-o` to specify your own filename:
```bash
icongrabber /Applications/Safari.app -o my-custom-name.png
```
## Development
### Build from Source
```bash
# Clone the repository
git clone https://github.com/macadmins/icongrabber.git
cd icongrabber
# Build
make build
# Run locally
./bin/icongrabber /Applications/Safari.app
```
### Run Tests
```bash
# Run the full test suite
make test
# Tests include:
# - Basic icon extraction
# - Multiple sizes (16, 32, 64, 128, 256, 512, 1024)
# - Custom output paths
# - Error handling
# - CLI argument parsing
```
See [tests/README.md](tests/README.md) for detailed test documentation.
### Clean Build Artifacts
```bash
make clean
```
### Continuous Integration
The project uses GitHub Actions for automated testing:
- Integration tests on every PR
- Multi-version testing (macOS 15, latest)
- Installation verification
- Swift syntax checking
View the [CI workflow](.github/workflows/ci.yml) for details.
## Documentation
- [Contributing Guide](CONTRIBUTING.md) - How to contribute
- [Release Guide](.github/RELEASE_GUIDE.md) - For maintainers: creating releases
- [Test Documentation](tests/README.md) - Test suite details
- [Scripts Documentation](scripts/README.md) - Helper scripts
- Man Page - `man icongrabber` (after installation)
## FAQ
**Q: What formats are supported?**
A: Currently PNG format only. Icons are extracted at the highest quality available.
**Q: How does the file size optimization work?**
A: The `--max-file-size` option uses macOS's built-in `sips` tool to compress the icon by converting to JPEG with varying quality levels, then back to PNG. This reduces file size while maintaining reasonable visual quality. You can specify sizes like `100KB`, `100K`, `2MB`, or `2M` (case-insensitive). If you don't specify an icon size with `-s`, the tool will automatically select an appropriate size based on your file size target.
**Q: What if an app doesn't have an icon?**
A: The tool will exit with an error code and display an error message.
**Q: Can I use this in my build scripts?**
A: Absolutely! The tool returns proper exit codes (0 for success, non-zero for errors) for easy integration.
**Q: Does this work with paths containing spaces?**
A: Yes! Just wrap the path in quotes: `icongrabber "/Applications/Visual Studio Code.app"`
**Q: Can I use `~` in paths?**
A: Yes, tilde expansion is supported: `icongrabber ~/Applications/MyApp.app`
## Contributing
Contributions are welcome! Feel free to:
- Report bugs
- Suggest features
- Submit pull requests
- Improve documentation
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
Built with Swift and AppKit for the macOS community.
---
**Made with ❤️ for macOS administrators, developers and designers**