Fetchtastic

A simple, cross-platform utility for downloading and managing Meshtastic firmware and client app releases.

Fetchtastic automatically downloads the latest Meshtastic firmware and selected client app assets from GitHub, with support for notifications, scheduling, and repository browsing.

Requires Python 3.11+; Python 3.10 and earlier are unsupported.

✨ Features

🔄 Automatic Downloads: Latest firmware and Meshtastic client app assets
⚡ Async Download Engine: aiohttp-based downloads with connection pooling and retry/backoff
📱 Cross-Platform: Linux, macOS, Windows, and Android (Termux)
🗂️ Repository Browser: Browse and download files from meshtastic.github.io
🔔 Notifications: Push notifications via NTFY
⏰ Scheduling: Automatic downloads via cron/startup scripts
🎯 Smart Selection: Choose specific devices, APKs, and desktop installers
📦 Auto-extraction: Extract firmware files from zip archives
✅ Stronger Integrity Checks: Hash-based verification and ZIP integrity validation
🚦 GitHub API Resilience: Centralized release fetching, defensive parsing, caching, and rate-limit-aware behavior
🧵 Parallel Validation: Release completeness checks run in parallel for faster scans
🔧 Easy Setup: One-command installation with guided setup

🚀 Quick Start

One-Line Installation

New installations use uv by default. Re-running the installer preserves a recognized existing uv, pipx, or pip installation instead of silently changing managers. On Linux, macOS, and Windows, uv can provide Python 3.11+ automatically; Termux uses its native Python package. Migration to uv is explicit.

Linux/MacOS/Android (Termux):

curl -sSL https://raw.githubusercontent.com/jeremiah-k/fetchtastic/main/src/fetchtastic/tools/setup_fetchtastic.sh | bash

Security Note: For security-conscious users, you can inspect the script before running it.

Windows (PowerShell):

irm https://raw.githubusercontent.com/jeremiah-k/fetchtastic/main/src/fetchtastic/tools/setup_fetchtastic.ps1 | iex

Security Note: For security-conscious users, you can inspect the script before running it.

Basic Usage

# Run setup (first time)
fetchtastic setup

# Download latest releases
fetchtastic download

# Browse repository files
fetchtastic repo browse

📖 Documentation

Installation Guides

Linux Installation - Complete installation guide for Linux distributions
macOS Installation - Installation guide for macOS with Homebrew
Windows Installation - Windows installation with integration features
Termux Installation - Android installation using Termux

Usage

Usage Guide - Complete guide to using Fetchtastic
Configuration Reference - YAML settings, advanced options, and latest symlink behavior

🔧 Commands

fetchtastic setup         # Run the setup process
fetchtastic download      # Download firmware and client app assets
fetchtastic cache clear   # Clear cached API data
fetchtastic repo browse   # Browse repository files
fetchtastic repo clean    # Clean repository downloads
fetchtastic topic         # Show NTFY topic
fetchtastic version       # Show version
fetchtastic clean         # Remove all configuration

🏗️ Architecture Highlights

Shared GitHub release source: Release parsing and validation are centralized for consistency across firmware and client app assets.
Async + sync compatibility: Async download paths are first-class, with sync fallbacks when async libraries are unavailable.
Defensive verification flow: Size checks, hash baselines, and ZIP integrity checks are combined to reduce false positives.
Better retry semantics: Retryable vs non-retryable errors are preserved to improve behavior and diagnostics.

📁 File Organization

Downloads are organized in a clean structure:

~/Downloads/Meshtastic/
├── app/
│   ├── v2.7.14/
│   │   ├── app-fdroid-universal-release.apk
│   │   ├── Meshtastic-2.7.14.dmg
│   │   └── release_notes-v2.7.14.md
│   ├── prerelease/   # Prerelease client app builds (optional)
│   └── snapshots/    # Rolling APK and desktop snapshot builds (opt-in)
├── firmware/
│   ├── v2.3.2/
│   ├── v2.3.1/
│   ├── repo-dls/      # Repository browser downloads
│   ├── prerelease/    # Prerelease firmware (optional)
│   └── nightlies/     # Rolling experimental firmware nightlies (opt-in)

APKs and desktop installers intentionally share app/<version>/ because they are treated as client app assets from the same release pipeline.

🔔 Notifications

Get notified when new releases are downloaded:

Enable NTFY during setup
Install the ntfy app or use the web interface
Subscribe to your unique topic
Receive push notifications for new downloads

⏰ Scheduling

Set up automatic downloads:

Linux/macOS: Cron jobs (daily at 3 AM)
Windows: Startup folder shortcuts
Termux: Boot scripts and cron jobs

🆙 Upgrading

Automatic (recommended):

Windows: Use Start Menu → Fetchtastic → "Check for Updates"
Linux/macOS/Termux: Re-run the installation script

Manual (use the manager that installed Fetchtastic):

uv tool upgrade fetchtastic
# Existing pipx installations:
pipx upgrade fetchtastic
# Existing pip installations: activate the environment that owns Fetchtastic,
# or invoke that environment's Python explicitly:
/path/to/owning/environment/bin/python -m pip install --upgrade fetchtastic

pip remains supported. See the platform guides for virtual environment installation and migration to uv; configuration and downloads are preserved.

🤝 Contributing

Contributions are welcome! Please feel free to:

Report bugs and issues
Suggest new features
Submit pull requests
Improve documentation

Visit the GitHub repository to get started.

🧪 Development & Testing

uv sync --locked --extra test
uv run --locked --no-sync python -m pytest tests/
uv run --locked --no-sync python scripts/build_and_check.py

For pip development, activate a Python 3.11+ virtual environment and run python -m pip install -e ".[test]" followed by python -m pytest tests/. See the testing guide for lock updates and build checks.

Test suite organization uses markers such as unit, integration, core_downloads, user_interface, configuration, and infrastructure.

📄 License

MIT License - see LICENSE for details.

Metadata

Release files for fetchtastic 0.11.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fetchtastic 0.11.5
File	Size	Uploaded
fetchtastic-0.11.5.tar.gz	660.8 kB	Oct 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for fetchtastic 0.11.5
File	Interpreter	ABI	Platform	Reset
fetchtastic-0.11.5-py3-none-any.whl 322.7 kB Oct 16, 2026	Python 3	none	any	Details

Total release size: 983.5 kB

Release files / fetchtastic-0.11.5.tar.gz

Download URL	fetchtastic-0.11.5.tar.gz
Size	660.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`eb5b62eb044682162ff7e98b6b1e1f4699d7ff9f5578d4abdaf81a4beb1d9aae`
BLAKE2b-256 checksum How to use checksums	`cf7a64c8f0581bd6e4e7feb66ec812181d37c75e9d1faee9f827a047a5d3c279`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/jeremiah-k/fetchtastic
Publishing commit: github.com/jeremiah-k/fetchtastic/tree/63fa17edd5b15983f1c5d4f9faff07043fec40d1

Workflow

Publishing configuration: github.com/jeremiah-k/fetchtastic/blob/63fa17edd5b15983f1c5d4f9faff07043fec40d1/.github/workflows/pypi-publish.yml
Publishing logs: github.com/jeremiah-k/fetchtastic/actions/runs/38839744317/attempts/1

Artifact

Subject: fetchtastic-0.11.5.tar.gz
SHA-256 checksum: eb5b62eb044682162ff7e98b6b1e1f4699d7ff9f5578d4abdaf81a4beb1d9aae Verifying attestations

Release files / fetchtastic-0.11.5-py3-none-any.whl

Download URL	fetchtastic-0.11.5-py3-none-any.whl
Size	322.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`88e79bd31f7b94e17305b98b5c26689d06e98f02202c202d1c34fff246a0f6c7`
BLAKE2b-256 checksum How to use checksums	`db3edc1a5cd3f0c9f01854fb0a4d7656b3ca098d8b1047a8b71ead56057fef48`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/jeremiah-k/fetchtastic
Publishing commit: github.com/jeremiah-k/fetchtastic/tree/63fa17edd5b15983f1c5d4f9faff07043fec40d1

Workflow

Publishing configuration: github.com/jeremiah-k/fetchtastic/blob/63fa17edd5b15983f1c5d4f9faff07043fec40d1/.github/workflows/pypi-publish.yml
Publishing logs: github.com/jeremiah-k/fetchtastic/actions/runs/38839744317/attempts/1

Artifact

Subject: fetchtastic-0.11.5-py3-none-any.whl
SHA-256 checksum: 88e79bd31f7b94e17305b98b5c26689d06e98f02202c202d1c34fff246a0f6c7 Verifying attestations