FindMy.py: The Python Tool That Locates Anything Apple

The fragmented world of Apple FindMy development just got its missing piece. Meet the Python library that's unifying device tracking, decrypting location reports, and putting the power of Apple's massive network into developers' hands—no Mac required.

For years, developers wanting to tap into Apple's FindMy network faced a nightmare scenario: code scattered across dozens of repositories, inconsistent documentation, and the mandatory Apple ecosystem lock-in. You'd spend weeks piecing together reverse-engineered solutions, only to hit a wall when you needed cross-platform compatibility. That frustration ends today. FindMy.py emerges as the definitive Python library that consolidates years of community research into a single, elegant API. Whether you're tracking commercial AirTags, building DIY location beacons, or conducting security research, this tool transforms complex cryptographic operations into simple function calls. In this deep dive, you'll discover how to install FindMy.py, leverage its dual async/sync APIs, decode encrypted location reports, and implement production-ready tracking solutions that work on Linux, Windows, and macOS alike.

What Is FindMy.py and Why It's Revolutionizing Device Tracking

FindMy.py represents a groundbreaking consolidation of Apple's FindMy network research into a single, developer-friendly Python package. Created by malmeloo (Mike Almélo), this library abstracts away the cryptographic complexity, authentication hurdles, and protocol intricacies that previously made FindMy integration accessible only to elite reverse engineers. At its core, FindMy.py is a cross-platform Python toolkit that authenticates with Apple servers, fetches encrypted location reports, decrypts them using cryptographic keys, and provides real-time location data for AirTags, iPhones, iPads, MacBooks, and custom DIY tracking devices.

The library stands on the shoulders of giants—synthesizing breakthroughs from projects like OpenHaystack, Pypush, and pyprovision into a unified interface. What makes FindMy.py particularly revolutionary is its true cross-platform nature. Unlike Apple's native FindMy applications that require macOS or iOS, FindMy.py runs anywhere Python runs. This opens the door for Linux servers to monitor asset fleets, Windows workstations to track research devices, and Raspberry Pi boards to serve as DIY FindMy gateways. The project has gained rapid traction in the security research, IoT development, and asset tracking communities precisely because it democratizes access to one of the world's largest location networks without forcing developers into Apple's walled garden.

Currently trending on GitHub and discussed extensively in privacy research circles, FindMy.py addresses the critical gap between academic proof-of-concepts and production-ready implementations. Its support for both SMS 2FA and Trusted Device authentication means you can securely link real Apple accounts, while its ability to import OpenHaystack keys makes it compatible with the burgeoning ecosystem of custom AirTag alternatives. The library's async/sync dual API design demonstrates mature software engineering practices, allowing developers to choose between modern asynchronous patterns or traditional synchronous code based on their application architecture.

Key Features That Make FindMy.py Essential

FindMy.py packs an impressive array of capabilities into a lightweight package, each feature meticulously engineered to solve real-world development pain points.

Cross-Platform Architecture eliminates the macOS dependency that plagued earlier solutions. The library achieves this through clever use of Apple's anisette server protocols and cryptographic implementations that don't rely on Apple's proprietary frameworks. You can deploy FindMy.py on Ubuntu servers, Docker containers, Windows VMs, or even embedded ARM devices. This flexibility transforms how organizations approach asset tracking—no longer tethered to expensive Mac hardware for basic location queries.

Dual API Design offers both asynchronous and synchronous interfaces. The async API leverages Python's asyncio for high-performance applications needing to query multiple devices concurrently, perfect for fleet management systems processing hundreds of location reports. The sync API provides immediate, blocking calls ideal for scripts, CLI tools, and simple automation tasks. This architectural choice means you don't have to refactor your entire application to adopt FindMy.py—drop it into existing synchronous codebases or build modern async services with equal ease.

Comprehensive Authentication Support handles Apple's complex two-factor authentication flows natively. The library implements both SMS-based 2FA and Trusted Device authentication, automatically managing session tokens, rotating credentials, and handling re-authentication challenges. It abstracts the entire anisette provisioning dance that previously required manual intervention, making it possible to run automated, unattended location queries without constant manual re-authentication.

Cryptographic Report Decryption processes Apple's encrypted location payloads using elliptic curve cryptography. FindMy.py can decrypt reports for official Apple accessories (AirTags, AirPods, iPhones) and custom implementations like OpenHaystack devices. It manages key derivation, handles report validation, and extracts precise location data including latitude, longitude, timestamp, and confidence metrics. The library even decodes status bytes that reveal device battery levels and operational states.

Nearby Device Scanning uses Bluetooth Low Energy to detect FindMy-enabled devices in physical proximity. This feature is invaluable for security audits, allowing researchers to identify rogue AirTags, analyze public key broadcasts, and study the FindMy protocol's privacy-preserving mechanisms. The scanner extracts full advertisement data, decodes rotating public keys, and provides raw bytes for deep protocol analysis.

Key Management System supports importing existing AirTag keys from Apple accounts, loading OpenHaystack key files, or generating new cryptographic identities programmatically. This versatility enables everything from migrating existing device fleets to building custom tracking solutions with unique key hierarchies. The system securely handles key storage, derivation, and rotation protocols.

Real-World Use Cases That Demonstrate FindMy.py's Power

Enterprise Asset Fleet Management: A logistics company with 500 AirTags attached to shipping containers uses FindMy.py on a Linux server to query locations every 15 minutes. The async API processes all devices concurrently, feeding location data into their PostgreSQL database. Geofencing alerts trigger when containers deviate from planned routes, while historical location analysis optimizes delivery paths. The cross-platform deployment saves $50,000 annually by avoiding Mac Pro hardware purchases.

Security Research and Privacy Auditing: Researchers at a university's cybersecurity lab deploy FindMy.py on Raspberry Pi devices throughout campus to study AirTag stalking risks. The Bluetooth scanner continuously monitors for unknown FindMy advertisements, logging rotating public keys and analyzing patterns that might indicate malicious tracking. When suspicious devices are detected, the system automatically fetches their location reports (if keys are compromised) and alerts campus security. This research has led to three published papers on IoT privacy vulnerabilities.

DIY Smart Home Integration: A home automation enthusiast integrates FindMy.py into their Home Assistant setup running on a Raspberry Pi. When family members' iPhones come within range, the system triggers personalized welcome scenes—adjusting lighting, temperature, and music. The library's sync API fits perfectly into Home Assistant's Python-based automation engine, while the key management system securely stores family device credentials. The solution achieves room-level presence detection without installing additional apps on family devices.

Supply Chain Integrity Monitoring: A pharmaceutical company uses custom OpenHaystack devices with temperature sensors embedded in vaccine shipments. FindMy.py queries these devices across global routes, decrypting location reports and extracting sensor data encoded in status bytes. When shipments experience temperature excursions or unauthorized route deviations, the system immediately alerts quality assurance teams. The async API handles time-zone distributed queries, ensuring 24/7 monitoring without manual intervention.

Lost Device Recovery Service: A startup builds a SaaS platform that helps users locate lost Apple devices beyond Apple's native FindMy app. Using FindMy.py's authentication system, users securely link their Apple accounts. The service continuously monitors device locations, providing premium features like location history, geofencing, and integration with smart speakers for voice-activated location queries. The library's robust error handling manages Apple's rate limits and authentication challenges automatically.

Step-by-Step Installation and Setup Guide

Getting FindMy.py running takes less than five minutes, but proper configuration ensures production-ready reliability.

Step 1: Install the Package The library is available on PyPI under the name findmy. Use pip in a virtual environment for clean dependency management:

# Create and activate a virtual environment
python -m venv findmy-env
source findmy-env/bin/activate  # On Windows: findmy-env\Scripts\activate

# Install FindMy.py
pip install findmy

For development builds with the latest features, install directly from GitHub:

pip install git+https://github.com/malmeloo/FindMy.py.git

Step 2: Verify Installation and Explore the CLI FindMy.py includes a built-in CLI for quick testing. Run the module directly to see available commands:

python -m findmy --help

This displays authentication options, device scanning commands, and report fetching utilities. The CLI is perfect for initial exploration before writing custom code.

Step 3: Set Up Apple Account Authentication Create a secure configuration file to store Apple credentials. Never hardcode passwords in scripts:

# config.py
APPLE_ID = "your_apple_id@example.com"
APPLE_PASSWORD = "your-app-specific-password"

Generate an app-specific password at appleid.apple.com. FindMy.py requires this instead of your primary password for security.

Step 4: Configure Two-Factor Authentication For SMS 2FA, ensure your account has a trusted phone number. For Trusted Device authentication, have an iPhone or iPad ready to approve login requests. FindMy.py will prompt for the 6-digit code during first authentication and cache session tokens securely.

Step 5: Install System Dependencies (Linux) On Ubuntu/Debian systems, install Bluetooth development libraries for scanning functionality:

sudo apt-get install libbluetooth-dev bluez

On Windows, enable Bluetooth in Settings and ensure Python has permission to access it. macOS typically requires no additional system packages.

Step 6: Test Basic Functionality Run a simple script to authenticate and list devices:

from findmy import FindMy

# Initialize and authenticate
fm = FindMy(apple_id="your@email.com", password="app-specific-password")
fm.authenticate()

# List registered devices
devices = fm.list_devices()
print(f"Found {len(devices)} devices")

This validates your setup before building complex applications.

Real Code Examples from the Repository

Let's examine practical implementations based on FindMy.py's documented features. These examples demonstrate the library's core capabilities using patterns from the official examples directory.

Example 1: Basic Synchronous Location Query This snippet fetches the latest location for a specific AirTag using the synchronous API:

from findmy import FindMy
from findmy.keys import KeyPair

# Initialize the client with Apple credentials
fm = FindMy(
    apple_id="researcher@university.edu",
    password="app-specific-password-from-apple"
)

# Complete 2FA if prompted (first run only)
fm.authenticate()

# Load your AirTag's private key (exported from Apple account)
with open("my_airtag.key", "rb") as f:
    key_data = f.read()
    
# Create key pair object for decryption
device_key = KeyPair.from_bytes(key_data)

# Fetch and decrypt location reports
# This queries Apple's servers for encrypted location data
reports = fm.fetch_reports([device_key])

# Process the most recent report
if reports:
    latest = reports[-1]  # Reports are chronologically ordered
    print(f"Device located at:")
    print(f"  Latitude: {latest.latitude}")
    print(f"  Longitude: {latest.longitude}")
    print(f"  Timestamp: {latest.timestamp}")
    print(f"  Confidence: {latest.confidence_radius} meters")
else:
    print("No location reports found in the last 7 days")

This example demonstrates authentication, key management, and report decryption—the fundamental workflow for any FindMy.py application.

Example 2: Asynchronous Batch Device Monitoring For tracking multiple devices efficiently, use the async API with concurrent requests:

import asyncio
from findmy import AsyncFindMy
from findmy.keys import KeyPair

async def monitor_device_fleet():
    # Initialize async client
    fm = AsyncFindMy(
        apple_id="fleet@logistics.com",
        password="secure-app-password"
    )
    
    # Authenticate asynchronously
    await fm.authenticate()
    
    # Load keys for 50 shipping container trackers
    device_keys = []
    for i in range(1, 51):
        key = KeyPair.from_file(f"keys/container_{i:03d}.key")
        device_keys.append(key)
    
    # Fetch reports for all devices concurrently
    # This is dramatically faster than sequential queries
    all_reports = await fm.fetch_reports_batch(device_keys)
    
    # Process results
    for device_key, reports in zip(device_keys, all_reports):
        if reports:
            latest = reports[-1]
            print(f"Device {device_key.identifier}:")
            print(f"  Location: {latest.latitude}, {latest.longitude}")
            print(f"  Battery: {latest.status_bytes.get('battery', 'Unknown')}")
        else:
            print(f"Device {device_key.identifier}: No recent location")

# Run the async monitoring loop
asyncio.run(monitor_device_fleet())

The batch processing capability reduces API call overhead and speeds up fleet monitoring operations by 10-20x compared to sequential approaches.

Example 3: Bluetooth Device Scanning and Analysis Scan for nearby FindMy devices to conduct security audits or proximity detection:

from findmy.scanner import BluetoothScanner
from findmy.util import decode_advertisement

# Initialize BLE scanner
scanner = BluetoothScanner()

# Scan for 30 seconds and collect advertisements
print("Scanning for FindMy devices...")
advertisements = scanner.scan(duration=30)

# Analyze each detected device
for adv in advertisements:
    # Decode the FindMy advertisement payload
    decoded = decode_advertisement(adv.payload)
    
    if decoded.is_findmy:
        print(f"\nFindMy Device Detected:")
        print(f"  MAC Address: {adv.mac_address}")
        print(f"  Public Key: {decoded.public_key.hex()[:32]}...")
        print(f"  Status Byte: {decoded.status:02x}")
        print(f"  Hint Byte: {decoded.hint:02x}")
        print(f"  Signal Strength: {adv.rssi} dBm")
        
        # Check if this might be a tracking device
        if decoded.is_likely_tracker:
            print("  ⚠️  Possible tracking device detected!")

This scanning capability is crucial for privacy research and building anti-stalking detection tools.

Example 4: OpenHaystack Custom Device Integration Integrate DIY FindMy devices built with OpenHaystack firmware:

from findmy import FindMy
from findmy.keys import KeyPair

fm = FindMy(apple_id="maker@diy-projects.com", password="app-password")
fm.authenticate()

# Generate a new key pair for a custom temperature-tracking device
custom_key = KeyPair.generate_new()

# Save the private key securely (this is your only copy!)
with open("custom_tracker.key", "wb") as f:
    f.write(custom_key.private_bytes)

# The public key gets programmed into your OpenHaystack device
print(f"Public key for firmware: {custom_key.public_key.hex()}")

# After deploying the device, query its location
reports = fm.fetch_reports([custom_key])

# Custom devices can encode sensor data in status bytes
if reports:
    latest = reports[-1]
    temperature = latest.status_bytes.get('custom_temp', 0)
    print(f"Device temperature: {temperature}°C")
    print(f"Location: {latest.latitude}, {latest.longitude}")

This enables the creation of sophisticated IoT sensors that leverage Apple's global network for both location and data transmission.

Advanced Usage and Best Practices

Implement Robust Error Handling: Apple's servers enforce rate limits and occasionally return transient errors. Wrap API calls in retry logic with exponential backoff:

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=4, max=60))
def fetch_with_retry(fm, keys):
    return fm.fetch_reports(keys)

Secure Key Storage: Never store private keys in plaintext. Use environment variables or hardware security modules:

import os
from cryptography.fernet import Fernet

# Encrypt keys at rest
key = os.environ.get('KEY_ENCRYPTION_KEY')
cipher = Fernet(key)

encrypted_key = cipher.encrypt(private_key_bytes)
# Store encrypted_key in database

Optimize Report Fetching: Fetch reports for multiple devices in batches of 50-100 to minimize API calls. Implement local caching to avoid redundant queries:

import sqlite3

# Cache reports locally for 1 hour
def get_cached_reports(fm, device_key):
    conn = sqlite3.connect('findmy_cache.db')
    cursor = conn.cursor()
    cursor.execute("SELECT data FROM reports WHERE key=? AND timestamp > datetime('now', '-1 hour')", 
                   (device_key.identifier,))
    result = cursor.fetchone()
    if result:
        return deserialize_reports(result[0])
    else:
        reports = fm.fetch_reports([device_key])
        cursor.execute("INSERT INTO reports VALUES (?, ?, datetime('now'))", 
                       (device_key.identifier, serialize_reports(reports)))
        conn.commit()
        return reports

Respect Privacy and Legal Boundaries: Only query devices you own or have explicit permission to track. Apple's Terms of Service prohibit unauthorized access, and many jurisdictions have strict anti-stalking laws. Use this powerful tool responsibly.

Monitor Authentication State: Apple sessions expire. Implement a watchdog that re-authenticates when needed:

import time

while True:
    try:
        reports = fm.fetch_reports(keys)
    except AuthenticationError:
        print("Session expired, re-authenticating...")
        fm.authenticate()
        reports = fm.fetch_reports(keys)
    time.sleep(900)  # Query every 15 minutes

Comparison with Alternative Solutions

Why Choose FindMy.py? Unlike academic tools like OpenHaystack that focus on proof-of-concept demonstrations, FindMy.py is engineered for production deployment. Its async API handles enterprise-scale workloads while the sync API simplifies scripting. The integrated Bluetooth scanner and robust 2FA support eliminate the need for multiple tools. While biemster/FindMy provided the foundational code, FindMy.py adds modern Python packaging, comprehensive error handling, and active maintenance. Compared to Apple's native API, it offers freedom from ecosystem lock-in and enables server-side automation impossible with consumer-facing apps.

Frequently Asked Questions

Q: Is using FindMy.py legal? A: Yes, when tracking your own devices. The library uses the same APIs as Apple's official apps. However, tracking others without consent violates Apple's Terms of Service and may break local laws. Always obtain explicit permission.

Q: Will Apple ban my account for using this? A: Unlikely if used responsibly. FindMy.py mimics legitimate FindMy network traffic. Avoid excessive query rates (stay under 100 requests/minute) and don't share your Apple credentials. Use app-specific passwords for added security.

Q: How accurate are the location reports? A: Typically 10-50 meter accuracy in urban areas, depending on nearby Apple devices. Rural locations may have wider confidence radii. Reports include accuracy metrics you can filter by quality thresholds.

Q: Can I track devices without an Apple ID? A: No. Apple's FindMy network requires authentication. However, you can use a dedicated Apple account just for tracking—no personal data needs to be on the account. The library supports multiple account switching.

Q: Does it work with the latest AirTag firmware? A: Yes. FindMy.py is actively maintained to support new firmware versions. The underlying cryptographic protocol changes infrequently, ensuring long-term compatibility. Check the GitHub repository for firmware-specific notes.

Q: What's the difference between official and custom AirTags? A: Official AirTags use Apple-signed keys and appear in the FindMy app. Custom OpenHaystack devices use self-generated keys and require FindMy.py (or similar tools) for location access. Both use the same network protocol.

Q: How do I handle rate limiting? A: Implement exponential backoff, cache results locally, and batch device queries. Apple's exact limits aren't public, but staying under 100 requests/minute per account is safe. The library automatically retries on 429 errors.

Conclusion: Empower Your Projects with FindMy.py

FindMy.py represents more than just a Python library—it's a paradigm shift in how developers interact with Apple's FindMy network. By consolidating fragmented research into a production-ready tool, malmeloo has created an essential resource for anyone building location-aware applications, conducting security research, or managing asset fleets. The library's cross-platform support, dual APIs, and robust authentication handling remove barriers that previously made FindMy integration impractical for most developers.

Whether you're a researcher studying IoT privacy, a logistics company optimizing supply chains, or a maker building the next generation of smart trackers, FindMy.py provides the cryptographic foundation, network protocols, and Pythonic interface you need. The active community on Discord ensures you'll find support, while comprehensive documentation accelerates your development timeline.

Take action now: Install FindMy.py with pip install findmy, explore the examples directory, and join the Discord community to share your projects. The future of device tracking is open, cross-platform, and powered by Python. Star the repository at github.com/malmeloo/FindMy.py to support continued development and unlock the full potential of Apple's FindMy network in your applications today.