Settings Reference
Every MacGet setting, its default, and its valid range — taken from AppSettings in the source.
Settings are stored in ~/Library/Application Support/Macget/settings.json.
Values are clamped when loaded, so a hand-edited file can't push MacGet outside
a valid range — it will be corrected silently on the next launch.
Unknown or missing keys fall back to their defaults rather than resetting the
whole file, so a settings.json written by an older version still loads.
General
| Setting | Default | Range / notes |
|---|---|---|
| Default destination | System Downloads folder | Falls back to ~/Downloads |
| Default thread count | 8 | 1–16 |
| Maximum concurrent downloads | 3 | 1–16 |
| Watch clipboard for URLs | Off | Polls the pasteboard at 1 Hz |
| Start downloads automatically | On | Off queues new downloads instead |
| Resume downloads on launch | On | Off moves them to paused instead |
| Sort completed downloads by type | Off | See organizing downloads |
| Completion notifications | Off | Posts a system notification per download |
Network
| Setting | Default | Range / notes |
|---|---|---|
| Global speed limit | Unlimited | Aggregate across all downloads; unset or ≤ 0 means unlimited |
| Request timeout | 30 s | 5–300 |
| Retries per chunk | 5 | 1–10. The engine's hard ceiling is five times this value |
| Proxy host | None | Both host and port must be set for the proxy to take effect |
| Proxy port | None | 1–65535 |
Changing network settings rebuilds the session
The engine owns its URLSession and rebuilds it when the proxy or timeout
changes. Downloads in flight are unaffected; the new settings apply to
subsequent requests.
Media
Only relevant when media extraction is enabled. See media downloads.
| Setting | Default | Range / notes |
|---|---|---|
| Enable media extraction | Off | Requires a terms-of-service acknowledgement |
| Write subtitles | Off | |
| Subtitle languages | en | Comma-separated (en,es) or all. Empty falls back to en |
| Embed metadata | Off | Writes title, uploader, and date into the file |
| Write thumbnail | Off | Saves the poster image alongside the download |
Browser integration
| Setting | Default | Range / notes |
|---|---|---|
| Auto-capture from the browser extension | On | Installs native-messaging host manifests and watches the inbox |
Turning this on is what registers MacGet with your browsers. See the browser extension guide.
Thread counts, in practice
The default of 8 threads per download is a reasonable middle. Some notes before you raise it:
- 16 is the hard ceiling, matching aria2's. It is not arbitrary — past roughly that point, most hosts stop rewarding additional connections.
- Per-host caps override your setting. If MacGet learned that a host rejects parallelism, it will not use more workers than that host tolerated, whatever you configure. See adaptive concurrency.
- Threads multiply with concurrent downloads. 16 threads across 3 concurrent downloads is 48 connections, which many networks and most CDNs will treat as abusive.
If downloads feel slow, the cause is more often the host than the thread count.
Related
Priorities & the Queue
How MacGet decides what downloads next — concurrency limits, High/Normal/Low priorities, and stable ordering.
Adaptive Concurrency
How MacGet discovers each host's real parallelism limit — probing up while it helps, demoting when the host pushes back, and remembering the result.
Organizing Downloads
Auto-sort finished downloads into category folders, and how MacGet resolves filename collisions.
Torrents
Downloading magnet links and .torrent files in MacGet — enabling support, seeding limits, file selection, and how the aria2 engine is installed.
New to MacGet? Install MacGet on your Mac with Homebrew or the signed DMG. It takes about a minute.