# RealReachability: ping-based internet checks for iOS, now a legacy repository

> RealReachability adds an ICMP ping probe on top of Apple's SCNetworkReachability API so an iOS app can tell a real internet connection from a local one. The README now marks the repository as legacy and points to RealReachability2, which changes who should install it.

**dustturtle/RealReachability** — We need to observe the REAL reachability of network. That's what RealReachability do.

- Repository: https://github.com/dustturtle/RealReachability
- Stars: 3,097 · Forks: 491
- Language: Objective-C
- License: MIT
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/dustturtle-realreachability

## What SCNetworkReachability cannot tell an iOS app

Apple's own documentation is quoted in the README with the sentence that reachability "does not guarantee that the data packet will actually be received by the host." That is the whole problem this library exists to solve. The SCNetworkReachability API, which the README notes is what the better known Reachability repository is built on, reports the state of the local connection: a Wi-Fi interface is up, a WWAN interface is up, or neither is. It does not report whether anything beyond that interface answers. A phone attached to a captive portal, a hotel access point that has stopped forwarding, or a router whose uplink is down can all look reachable to that API while every request your app makes times out.

RealReachability is for iOS developers who need the second answer, not the first. It is written in Objective-C, distributed through CocoaPods and Carthage, and it targets apps that want a status callback rather than a raw socket state. The README describes the combination as a ping module plus SCNetworkReachability, with a finite state machine deciding which transitions are worth reporting to the application.

## Ping plus SCNetworkReachability, filtered by a state machine

The mechanism has three parts. SCNetworkReachability supplies the local interface state. A ping helper sends ICMP probes to a host to establish whether traffic actually gets through. A finite state machine sits in front of both and, in the README's wording, confirms "that only status change will be sent to application." That last part matters more than it sounds: a naive implementation that fires a notification on every probe result will wake your observers constantly on a flaky link.

The API surface is small. GLobalRealReachability is the shared entry point, and startNotifier begins observation. Status is reported as ReachabilityStatus values, and the README's example switch handles RealStatusNotReachable, RealStatusViaWiFi and RealStatusViaWWAN. Two hosts are configurable: hostForPing and hostForCheck. The README says the default ping host is www.apple.com and recommends setting one host you control alongside one public host. Version 1.2.0 introduced what the README calls a "doublecheck" feature using those two hosts, and the repository layout shows the implementation split into a RealReachability directory plus a testRealReachability target.

## Installing the pod and getting a first status callback

The README gives CocoaPods as the primary path. The Podfile shown there pins the platform to iOS 12.0 and declares the pod without a version constraint, so the resolver picks the newest published version, which the README's badge identifies as 1.4.1.

```ruby
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '12.0'

pod 'RealReachability'
```

Run pod install after saving that file.

```bash
$ pod install
```

Carthage is the alternative: the README gives a Cartfile line of github "dustturtle/RealReachability", and manual integration means adding the RealReachability folder to the project directly. Whichever route you take, the README states that the SystemConfiguration framework must be added to your project.

Start the notifier in didFinishLaunchingWithOptions, which is where the README suggests doing it.

```objective-c
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [GLobalRealReachability startNotifier];
    return YES;
}
```

Then register for kRealReachabilityChangedNotification and read the status from the notification object. If you only need the answer once, for example before a retry, call reachabilityWithBlock and switch on the status it hands back; the README notes that this call refreshes currentReachabilityStatus synchronously, which means it blocks until the probe finishes. That synchronous refresh is the detail most likely to surprise you in production.

```objective-c
[GLobalRealReachability reachabilityWithBlock:^(ReachabilityStatus status) {
    switch (status)
    {
        case RealStatusNotReachable:
            break;
        case RealStatusViaWiFi:
            break;
        case RealStatusViaWWAN:
            break;
        default:
            break;
    }
}];
```

## The blocking call and the host you have to keep alive

reachabilityWithBlock is not a background convenience. Because it refreshes the status synchronously, calling it on the main thread before a network request means the UI waits for an ICMP round trip, and on a network that is dropping packets that wait is bounded by the ping timeout, not by your patience. Treat it as something to call from a background queue or to avoid on the critical path.

The second constraint is the hosts you choose. The README is explicit that the host you set must be available for pinging and suggests a large, stable website. If you point hostForPing at an internal server that blocks ICMP, the library will report no reachability while the app's HTTP requests succeed, which is a worse failure than the one you were trying to detect. Your own host needs to answer pings from every network your users sit behind, including mobile carriers that filter ICMP.

The third limitation is the project's own status. The README carries a migration notice stating that this repository is now legacy and is no longer actively maintained, and directs readers to RealReachability2. The most recent release listed on the repository is 1.3.0 from 2018-06-28, which introduced the VPN check, even though the README badge advertises 1.4.1. The last push to the repository was on 2026-04-29, so the code is not frozen, but the README's own framing and the age of the tagged releases are what a new adopter should weigh.

## How this differs from Reachability and ReachabilitySwift

The README names tonymillion/Reachability as the well known alternative and states the difference plainly: those tools are supported by the SCNetworkReachability API and report local connection status. RealReachability adds the ping probe and the state machine on top. If your app only needs to know whether the Wi-Fi interface is up, for example to choose between a cellular and a Wi-Fi upload policy, the lighter library is the correct choice and this one adds a network probe you do not need. ReachabilitySwift, which appears in the related searches, is the Swift-facing library in that same family and follows the same SCNetworkReachability basis.

The successor is the more direct comparison. The README describes RealReachability2 as combining NWPathMonitor, HTTP HEAD and ICMP Ping, with a Swift target for iOS 13 and above using an async/await API and an Objective-C target for iOS 12 and above using notifications. It also exposes probe modes: parallel, HTTP-only, or ICMP-only. That HTTP HEAD option is the meaningful architectural difference, because it removes the dependency on ICMP being permitted on the path. RealReachability has no equivalent mode in the documented API.

## Licence, maintenance and what upgrading costs

The repository is MIT licensed, which permits use in closed source applications; the LICENSE file sits at the top level alongside RealReachability.podspec. Nothing here suggests a licence change for the successor, but if you migrate you should read that repository's licence yourself rather than assume it carries over.

The upgrade cost is the part worth planning. There is no documented migration guide from this library to RealReachability2, and the APIs do not line up: this one exposes GLobalRealReachability, kRealReachabilityChangedNotification, hostForPing and hostForCheck, while the successor is described with async/await on Swift and notifications on Objective-C. Any call site that switches on RealStatusViaWiFi, RealStatusViaWWAN and RealStatusNotReachable has to be rewritten against the new status model. The pod subspecs add another wrinkle: the README documents RealReachability/Ping and RealReachability/Connection as separate subspecs for using PingHelper or LocalConnection alone, so a project that depends on a subspec has more surface to port than one that only uses the top level pod.

## Conclusion

Adopt RealReachability only if you are maintaining an existing Objective-C app that already depends on it and you cannot move yet; the README itself calls this repository legacy and directs new work to RealReachability2. New projects should start on RealReachability2 instead. Before committing, verify three things in your own tree: that the SystemConfiguration framework is linked, that the two hosts you assign to hostForPing and hostForCheck actually answer ICMP from your network, and whether the podspec version you resolve matches the 1.3.0 release listed on the repository rather than the 1.4.1 badge shown in the README.

## FAQ

### What is RealReachability used for?

It reports whether an iOS device has real internet access rather than only a local connection, by combining SCNetworkReachability with an ICMP ping probe and a finite state machine that emits notifications only on status changes.

### Is RealReachability still maintained?

The README states that the repository is now legacy and is no longer actively maintained, and it directs readers to migrate to RealReachability2. The last push to the repository was on 2026-04-29, and the most recent release listed is 1.3.0 from 2018-06-28.

### How do I install RealReachability in an iOS project?

The README gives CocoaPods as the main route with a Podfile entry of pod 'RealReachability' on a platform of iOS 12.0 or later, and Carthage with a Cartfile line of github "dustturtle/RealReachability". Manual integration means adding the RealReachability folder to the project, and the SystemConfiguration framework must be linked either way.

### Which host does RealReachability ping by default?

The README states that if you do not set one, the default ping host is www.apple.com. It recommends setting hostForPing and hostForCheck to two hosts, one you control and one public, and warns that the host you choose must be available for pinging.

## Sources

- [dustturtle/RealReachability on GitHub](https://github.com/dustturtle/RealReachability)
- [Issues](https://github.com/dustturtle/RealReachability/issues)
- [License: MIT](https://github.com/dustturtle/RealReachability/blob/master/LICENSE)
- [README](https://github.com/dustturtle/RealReachability/blob/master/README.md)
- [Releases](https://github.com/dustturtle/RealReachability/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dustturtle-realreachability