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

> Easily download specific historical app versions with IPATool. Use list-versions to find the External Version ID, then download your desired build from Apple's archives.

- Repository: [Majd/ipatool](https://github.com/majd/ipatool)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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](https://github.com/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`](https://github.com/majd/ipatool/blob/main/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.

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

```

The output displays every available version in a table format:

```text
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`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/cmd/download.go)【download.go†L52-L57】, to specify the exact build you want. The low-level implementation in [`pkg/appstore/appstore_download.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_download.go) constructs the HTTP request to Apple's download endpoint using this UUID, bypassing the default "latest version" logic.

```bash
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.

```bash
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`](https://github.com/majd/ipatool/blob/main/cmd/list_versions.go)** – Implements the CLI interface for the `list-versions` command, parsing flags and displaying the version metadata table.
- **[`cmd/download.go`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/cmd/list_versions.go), [`cmd/download.go`](https://github.com/majd/ipatool/blob/main/cmd/download.go), [`pkg/appstore/appstore_list_versions.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_list_versions.go), and [`pkg/appstore/appstore_download.go`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_download.go).