How to Download a Specific Historical Version of an App Using IPATool

Use the list-versions command to obtain the External Version ID (UUID) for your target build, then pass that identifier to download via the --external-version-id flag to retrieve any historic version Apple still hosts.

IPATool is a command-line utility that enables direct interaction with the iOS App Store for searching, purchasing, and downloading IPA files. As implemented in the majd/ipatool repository, the tool supports retrieving historical app versions by leveraging Apple's External Version ID system, allowing you to download specific builds rather than being limited to the latest release.

Step 1: Retrieve the External Version ID

Before downloading a historical version, you must identify the specific External Version ID—a UUID that uniquely identifies each build stored by Apple.

Using the list-versions Command

Execute the list-versions command with either the --app-id or --bundle-identifier flag to query all available versions for a specific app. According to the source code in cmd/list_versions.go【list‑versions.go†L20-L38】, this command interfaces with Apple's version-lookup API to return metadata including version numbers, release dates, and the critical External Version IDs.

ipatool list-versions --bundle-identifier com.example.myapp

The output displays every available version in a table format:

Version    External Version ID                      Date
1.2.3      6A1B2C3D-4E5F-6789-ABCD-EF0123456789     2023-04-15
1.2.2      5B2C3D4E-5F6A-7890-BCDE-F12345678901     2023-03-30
1.2.1      4C3D4E5F-6A7B-8901-CDEF-234567890123     2023-03-15

Copy the External Version ID corresponding to your desired version. The underlying implementation in pkg/appstore/appstore_list_versions.go handles the HTTP request to Apple's servers to retrieve this metadata.

Step 2: Download the Historical Version

Once you possess the External Version ID, you can target that specific build for download rather than the current App Store version.

Using the --external-version-id Flag

The download command accepts the --external-version-id flag, declared in cmd/download.go【download.go†L52-L57】, to specify the exact build you want. The low-level implementation in pkg/appstore/appstore_download.go constructs the HTTP request to Apple's download endpoint using this UUID, bypassing the default "latest version" logic.

ipatool download \
    --bundle-identifier com.example.myapp \
    --external-version-id 6A1B2C3D-4E5F-6789-ABCD-EF0123456789 \
    --output /tmp/MyApp_1.2.3.ipa

Handling License Acquisition

If the target app has not been purchased on the Apple ID you are using, append the --purchase flag to the download command. IPATool will automatically acquire the license before attempting the download, utilizing the same authentication flow that handles account login and password-token expiry.

ipatool download \
    --bundle-identifier com.example.myapp \
    --external-version-id 6A1B2C3D-4E5F-6789-ABCD-EF0123456789 \
    --purchase \
    --output /tmp/MyApp_1.2.3.ipa

Technical Implementation Details

The workflow relies on two distinct components within the IPATool architecture:

• cmd/list_versions.go – Implements the CLI interface for the list-versions command, parsing flags and displaying the version metadata table.
• cmd/download.go – Defines the --external-version-id flag and orchestrates the download workflow, including retry logic for authentication and license acquisition.
• pkg/appstore/appstore_list_versions.go – Contains the core logic for querying Apple's version-history API and extracting External Version IDs.
• pkg/appstore/appstore_download.go – Builds the actual HTTP request to Apple's download servers, inserting the External Version ID into the request payload to retrieve the specific historic bundle.

Because both commands share the same internal App Store client, authentication state (including session tokens and credentials) persists between listing versions and downloading your selected build.

Summary

• Historical downloads require two steps: First query available versions with list-versions, then download using the specific External Version ID.
• External Version IDs are UUIDs: These unique identifiers—not version numbers—are required to pinpoint specific builds in Apple's infrastructure.
• Use --external-version-id with download: This flag, defined in cmd/download.go, directs the tool to fetch a specific historic build rather than the latest version.
• Add --purchase if needed: This flag triggers automatic license acquisition for apps not yet owned by the authenticated Apple ID.
• File references: The functionality spans cmd/list_versions.go, cmd/download.go, pkg/appstore/appstore_list_versions.go, and pkg/appstore/appstore_download.go.

Frequently Asked Questions

What is an External Version ID in IPATool?

An External Version ID is a UUID (Universally Unique Identifier) that Apple assigns to every build of an app stored on their servers. According to the implementation in pkg/appstore/appstore_list_versions.go, IPATool retrieves these IDs from Apple's version-history API to enable precise targeting of specific builds rather than relying on version numbers, which may not be unique across different app bundles or platforms.

Can I download any historical version of an iOS app?

You can only download versions that Apple still retains on their download servers. When you run ipatool list-versions, the command queries Apple's infrastructure and displays only the versions currently available for distribution. If a version is removed from Apple's servers (typically very old builds), it will not appear in the list and cannot be downloaded even with the correct External Version ID.

Do I need to purchase the app before downloading an old version?

Yes, you must own a license for the app on the Apple ID you are using. If you attempt to download without purchasing first, the operation will fail. Add the --purchase flag to your download command to automatically acquire the license before the download begins. This is handled by the same authentication client that manages your login session, as implemented in the download workflow.

Why can't I just use the version number (like 1.2.3) to download?

Apple's download API requires the External Version ID (UUID) to locate specific builds within their content delivery network. Version numbers like "1.2.3" are not guaranteed to be unique identifiers in Apple's backend systems, and multiple platforms or regional variants might share the same version string. The UUID ensures IPATool requests the exact binary you intend to retrieve, as specified in the request construction logic within pkg/appstore/appstore_download.go.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}