https://github.com/anthonysgro/geospoof
Browser extension to spoof your geolocation, timezone, and prevent WebRTC IP leaks.
https://github.com/anthonysgro/geospoof
browser firefox gecko geolocation privacy security spoof spoofing spoofing-detection timezone vpn
Last synced: 27 days ago
JSON representation
Browser extension to spoof your geolocation, timezone, and prevent WebRTC IP leaks.
- Host: GitHub
- URL: https://github.com/anthonysgro/geospoof
- Owner: anthonysgro
- License: mit
- Created: 2026-03-02T02:00:24.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-26T04:51:29.000Z (28 days ago)
- Last Synced: 2026-05-26T06:33:15.524Z (28 days ago)
- Topics: browser, firefox, gecko, geolocation, privacy, security, spoof, spoofing, spoofing-detection, timezone, vpn
- Language: TypeScript
- Homepage: https://www.geospoof.com
- Size: 53.8 MB
- Stars: 29
- Watchers: 1
- Forks: 2
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# GeoSpoof
**Your VPN changes your IP address. Your browser is still telling websites where you actually are.**
[](LICENSE)
[](https://geospoof.com)
[](https://addons.mozilla.org/firefox/addon/geo-spoof/)
[](https://chromewebstore.google.com/detail/geospoof/dgdbdodafgaeifgajaajohkjjgobcgje)
[](https://apps.apple.com/app/geospoof/id6765719745)
[](https://github.com/anthonysgro/geospoof/releases)
## Getting started
### Install
| Browser | Store | Works on |
| :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| [
](https://addons.mozilla.org/firefox/addon/geo-spoof/) | [Firefox Add-ons](https://addons.mozilla.org/firefox/addon/geo-spoof/) | Firefox 140+ on desktop and Android |
| [
](https://chromewebstore.google.com/detail/geospoof/dgdbdodafgaeifgajaajohkjjgobcgje) | [Chrome Web Store](https://chromewebstore.google.com/detail/geospoof/dgdbdodafgaeifgajaajohkjjgobcgje) | Chrome, Brave, Edge, Opera, and other Chromium browsers |
| [
](https://apps.apple.com/app/geospoof/id6765719745) | [App Store](https://apps.apple.com/app/geospoof/id6765719745) | Safari on iOS, iPadOS, and macOS |
| [
](https://github.com/anthonysgro/geospoof/releases/latest) | [GitHub Releases (macOS DMG)](https://github.com/anthonysgro/geospoof/releases/latest) | Safari on macOS — direct download, no Apple ID required — [setup below](#from-github-releases-macos-direct-download) |
| [
](https://github.com/anthonysgro/geospoof/releases) | [GitHub Releases](https://github.com/anthonysgro/geospoof/releases) | Firefox self-hosted signed XPI — [setup below](#from-github-releases-firefox-self-hosted) |
Safari setup — enabling after install
After installing on Safari, tap the puzzle piece icon (or go to Safari Settings → Extensions) and enable GeoSpoof for the sites you want to protect. On iOS/iPadOS, you can also enable it per-site from the **AA** menu in the address bar.
Other install paths — macOS DMG, self-hosted XPI, from source
#### From GitHub Releases (macOS direct download)
If you'd rather not sign in to the App Store, you can install GeoSpoof from a notarized DMG distributed through GitHub Releases. Same code as the App Store build — signed with our Developer ID and notarized by Apple, so Gatekeeper accepts it on first launch.
1. Go to the [Releases](https://github.com/anthonysgro/geospoof/releases) page
2. Download `geospoof-macos-v.dmg` from the latest release
3. Double-click the DMG and drag **GeoSpoof.app** to your **Applications** folder
4. Launch GeoSpoof once from `/Applications` (the first launch enables the Safari extension)
5. Open Safari → Settings → Extensions, enable **GeoSpoof**, and grant the website permissions you want
> **First launch:** macOS will ask "GeoSpoof was downloaded from the internet — are you sure you want to open it?" the first time. Click **Open** — this only appears once. The wrapper app's window just confirms the extension is active; you'll spend the rest of your time in Safari.
> **Updates:** the direct-download build does not auto-update. To upgrade, re-download the latest DMG and replace `GeoSpoof.app` in `/Applications`. Your settings persist across upgrades. If you'd prefer auto-updates, install from the [App Store](https://apps.apple.com/app/geospoof/id6765719745) instead.
> **Requirements:** macOS 11+ on Apple Silicon or Intel. iOS / iPadOS users still need the [App Store](https://apps.apple.com/app/geospoof/id6765719745) build — Apple does not allow sideloading Safari extensions on those platforms.
#### From GitHub Releases (Firefox self-hosted)
Each release includes a self-hosted signed XPI alongside the AMO submission. The self-hosted XPI uses a 4-segment version (e.g., `1.18.0.42`) to avoid collisions with the AMO listing.
1. Go to the [Releases](https://github.com/anthonysgro/geospoof/releases) page
2. Download `geospoof-firefox-v-signed.xpi` from the latest release
3. In Firefox, open `about:addons`
4. Click the gear icon (⚙) and select **Install Add-on From File…**
5. Select the downloaded `.xpi` file
The signed XPI works on standard Firefox with no extra configuration. Once installed, Firefox automatically checks for and installs new versions via the self-hosted update manifest. If you later install from AMO, Firefox will auto-upgrade to it since AMO releases use a higher base version.
> **Note:** An unsigned `geospoof-firefox-v-unsigned.xpi` is also included in each release for Firefox forks that don't support AMO signatures. Most users should use the signed version.
#### From source
See [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions.
### Usage
1. Click the GeoSpoof icon in your toolbar
2. Search for a city, enter coordinates manually, or use "Sync with VPN" to auto-detect your VPN exit region
3. Enable "Location Protection" and "WebRTC Protection"
4. Refresh open tabs to apply
5. Confirm it's working at [geospoof.com/test](https://geospoof.com/test) — a live dashboard that shows every signal GeoSpoof overrides, running 110 tests against your browser
See [docs/USER_GUIDE.md](docs/USER_GUIDE.md) for details.
## Why GeoSpoof?
A VPN changes your IP, but your browser still leaks your real location through the Geolocation API, timezone offsets, `Intl.DateTimeFormat`, WebRTC, and more. Sites cross-reference these signals against your IP — when they don't match, you're flagged.
GeoSpoof overrides every one of those channels so your browser reports a consistent, chosen location instead of your real one. Set it to match your VPN, mismatch it on purpose, or pick anywhere in the world.
- **VPN Region Sync** — detects your VPN exit IP and sets your location to match. One click.
- **Manual control** — search for a city or enter coordinates directly.
- **Full signal alignment** — geolocation, timezone, Date APIs, Intl, Temporal, and WebRTC all report the same place.
- **Anti-fingerprinting** — overrides are disguised to pass native code checks used by real-world fingerprinting scripts.
- **Cross-browser** — Firefox, Chrome, Brave, Edge, and Safari. Single codebase, MV3.
> **Note:** Use of this tool may violate the Terms of Service of certain websites. Use responsibly.
### What This Does NOT Do
GeoSpoof is designed to work alongside a VPN, not replace one.
- Does NOT spoof your IP address (use a VPN for that)
- Does NOT change browser language or locale
- Does NOT bypass server-side detection (IP, payment info, account history)
- Does NOT track your browsing activity, collect telemetry, or store data on external servers. Some features (city search, VPN sync) call third-party APIs to function. See [External Services](#external-services) for exactly what's sent and to whom.
- Does NOT provide forensic-level anti-fingerprinting. Web Workers run in an isolated thread that extensions cannot inject into, meaning timezone can leak through that channel. Engine-level API tampering is also detectable by dedicated tools. For extreme threat models, use [Tor Browser](https://www.torproject.org/) or [Mullvad Browser](https://mullvad.net/browser) instead. GeoSpoof's goal is to present a plausible, consistent location identity — not to defeat forensic fingerprinting.
## Overridden APIs
When protection is enabled, GeoSpoof overrides browser APIs synchronously at `document_start` before any page JavaScript runs. Covered APIs include:
- **Geolocation** — `navigator.geolocation.getCurrentPosition/watchPosition`, `navigator.permissions.query`
- **Date & Timezone** — `Date` constructor, `Date.parse`, all `Date.prototype` getters and formatters, `getTimezoneOffset`
- **Intl** — `Intl.DateTimeFormat` constructor and `resolvedOptions`
- **Temporal** — `Temporal.Now.*` (feature-detected)
- **WebRTC** — via browser privacy API, no script injection needed
- **Anti-fingerprinting** — `Function.prototype.toString` returns `[native code]` for all overrides; iframes patched on insertion
For the full API reference, see [docs/API.md](docs/API.md).
## External Services
| Service | When | What's sent | Source |
| ------------------------------------------------------------------ | ------------------------------ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [Nominatim](https://nominatim.org/) (OpenStreetMap) | City search, reverse geocoding | Search query or coordinates | [GitHub](https://github.com/osm-search/Nominatim) |
| [browser-geo-tz](https://www.npmjs.com/package/browser-geo-tz) CDN | Timezone resolution | HTTPS range requests for boundary data chunks (coordinates stay local) | [GitHub](https://github.com/kevmo314/browser-geo-tz) |
| [ipify](https://www.ipify.org/) | VPN sync enabled | HTTPS request to detect your public IP | [GitHub](https://github.com/rdegges/ipify-api) |
| [GeoJS](https://www.geojs.io/) | VPN sync enabled | Your public IP (to geolocate VPN exit region) | [GitHub](https://github.com/jloh/geojs) |
| [FreeIPAPI](https://freeipapi.com/) | VPN sync fallback | Your public IP (fallback geolocation service) | Closed source ([Privacy Policy](https://freeipapi.com/privacy-policy)) |
| [ReallyFreeGeoIP](https://reallyfreegeoip.org/) | VPN sync fallback | Your public IP (fallback geolocation service) | [GitHub](https://github.com/reallyfreegeoip/reallyfreegeoip) |
| [ipinfo.io](https://ipinfo.io/) | VPN sync fallback | Your public IP (fallback geolocation service) | Closed source ([Privacy Policy](https://ipinfo.io/privacy-policy)) |
> **VPN Sync privacy note:** When you enable "Sync with VPN," your public IP is sent to `api.ipify.org` and up to four geolocation services (`get.geojs.io`, `free.freeipapi.com`, `reallyfreegeoip.org`, `ipinfo.io`) in parallel over HTTPS to determine your VPN exit region. Your IP is never saved to disk — it's held only in memory and cleared when you disable VPN sync. See [PRIVACY_POLICY.md](PRIVACY_POLICY.md) for full details.
No data is sent to the extension developer. See [PRIVACY_POLICY.md](PRIVACY_POLICY.md).
## Development
See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, scripts, testing, and the release pipeline.
## Legal
Using location spoofing may violate terms of service of streaming, financial, or e-commerce platforms. You are responsible for compliance. See [PRIVACY_POLICY.md](PRIVACY_POLICY.md) for full details.
## License
MIT — see [LICENSE](LICENSE).
## Links
- [Website — geospoof.com](https://geospoof.com)
- [Verify your protection — geospoof.com/test](https://geospoof.com/test)
- [User Guide](docs/USER_GUIDE.md)
- [API Documentation](docs/API.md)
- [How Browsers Track Location](docs/BACKGROUND.md)
- [Privacy Policy](PRIVACY_POLICY.md)
- [Contributing](CONTRIBUTING.md)
- [Report Issues](https://github.com/anthonysgro/geospoof/issues)
- [Buy me a coffee](https://buymeacoffee.com/sgro)
## Acknowledgments
- [Nominatim](https://nominatim.org/) for geocoding
- [browser-geo-tz](https://github.com/kevmo314/browser-geo-tz) for timezone boundary-data lookup
- [BrowserLeaks](https://browserleaks.com/) for testing tools