# How to Run GhostTrack Locally: Complete Installation Guide

> Learn how to run GhostTrack locally with this complete installation guide. Clone the repo, install dependencies, and launch the interactive CLI in just a few steps.

- Repository: [K1LLU/GhostTrack](https://github.com/HunxByts/GhostTrack)
- Tags: how-to-guide
- Published: 2026-04-29

---

**Clone the HunxByts/GhostTrack repository, install the Python dependencies from [`requirements.txt`](https://github.com/HunxByts/GhostTrack/blob/main/requirements.txt), and execute `python3 GhostTR.py` to launch the interactive CLI menu.**

GhostTrack is a lightweight, single-file OSINT tool developed by HunxByts that runs entirely in your local terminal. This Python CLI application provides three investigative features—IP tracking, phone number analysis, and username enumeration—without requiring external APIs or complex configuration. Whether you are a security researcher or privacy enthusiast, learning how to run GhostTrack locally gives you immediate access to these open-source intelligence capabilities.

## What is GhostTrack?

GhostTrack is a standalone Python script packaged in [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py) that performs OSINT-style investigations through an interactive menu system. The tool relies on minimal external dependencies—specifically the `requests` library for HTTP operations and the `phonenumbers` library for phone validation. All functionality is self-contained within a single file, making local deployment straightforward on any system with Python 3 installed.

## Prerequisites

Before running GhostTrack locally, ensure your system meets these requirements:

- **Python 3** installed (verified compatible with standard Python 3.x distributions)
- **pip** package manager
- **Git** for cloning the repository
- Internet connection (required for IP geolocation lookups and username verification)

## Installation Steps

Follow these steps to set up GhostTrack on your local machine:

1. Clone the repository from GitHub:

```bash
git clone https://github.com/HunxByts/GhostTrack.git
cd GhostTrack

```

2. Install the required Python packages:

```bash
pip3 install -r requirements.txt

```

The [`requirements.txt`](https://github.com/HunxByts/GhostTrack/blob/main/requirements.txt) file contains two dependencies:
- `requests` – Handles HTTP requests for IP lookups and username verification
- `phonenumbers` – Parses and validates international phone number formats

## Running GhostTrack Locally

Launch the tool by executing the main script:

```bash
python3 GhostTR.py

```

Upon execution, the `main()` function at the bottom of [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py) initializes the program flow:

1. **Banner Display**: The `run_banner()` function clears the terminal and displays an ASCII art banner
2. **Menu Rendering**: The `option()` function builds the interactive menu from the global `options` list
3. **User Input**: You select a numeric option (0-4) which passes to `execute_option()`
4. **Function Dispatch**: The `call_option()` method validates your selection via `is_in_options` and invokes the corresponding tracking function

The menu presents these choices:

```

[ 1 ] IP Tracker
[ 2 ] Show Your IP
[ 3 ] Phone Number Tracker
[ 4 ] Username Tracker
[ 0 ] Exit

```

After completing any tracking operation, the tool pauses with "Press enter to continue" before recursively calling `main()` to display the menu again.

## Using the OSINT Features

### IP Tracker

Select option **1** to query IP geolocation data. The `IP_Track()` function sends a GET request to `http://ipwho.is/` and returns:

- Country and city location
- Latitude and longitude coordinates
- ASN and ISP information
- Timezone data
- Direct Google Maps link

Example interaction:

```text
[ + ] Select Option : 1

 Enter IP target : 8.8.8.8

 IP target       : 8.8.8.8
 Type IP         : IPv4
 Country         : United States
 City            : Mountain View
 Latitude        : 37.386
 Longitude       : -122.0838
 Maps            : https://www.google.com/maps/@37, -122,8z
 ...

```

### Phone Number Tracker

Choose option **3** to analyze phone numbers. The `phoneGW()` function uses the **phonenumbers** library to parse the input and extract:

- Geographic region and country
- Carrier/operator information
- Timezone associations
- Number type (mobile, landline, VoIP)
- Validation status

Example usage:

```text
[ + ] Select Option : 3

 Enter phone number target [+6281xxxxxxxxx] : +14155552671

 Location             : United States
 Region Code          : US
 Timezone             : America/Los_Angeles
 Operator             : AT&T
 Valid number         : True
 ...

```

### Username Tracker

Select option **4** to check username availability across social platforms. The `TrackLu()` function iterates through hard-coded URL templates in [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py), making HTTP requests to detect existing profiles:

```text
[ + ] Select Option : 4

 Enter Username : exampleuser

 [ + ] Facebook : https://www.facebook.com/exampleuser
 [ + ] Twitter  : Username not found !
 [ + ] Instagram: https://www.instagram.com/exampleuser
 ...

```

This feature checks platforms including Facebook, Twitter, Instagram, and others by requesting profile URLs and interpreting HTTP status codes.

## Key Files in the Repository

Understanding these files helps you troubleshoot and customize GhostTrack:

- **[`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py)** – Contains the complete application logic, including the `main()` entry point, menu system (`option()`, `execute_option()`), and all tracking functions (`IP_Track`, `showIP`, `phoneGW`, `TrackLu`)
- **[`requirements.txt`](https://github.com/HunxByts/GhostTrack/blob/main/requirements.txt)** – Lists the minimal Python dependencies (`requests` and `phonenumbers`)
- **[`README.md`](https://github.com/HunxByts/GhostTrack/blob/main/README.md)** – Provides additional context and screenshots for the project

## Summary

Running GhostTrack locally requires only three steps: cloning the HunxByts/GhostTrack repository, installing dependencies via `pip3 install -r requirements.txt`, and executing `python3 GhostTR.py`. The tool operates as a single-file Python application with no persistent state or configuration files needed. Key capabilities include IP geolocation lookups via `ipwho.is`, phone number validation through the `phonenumbers` library, and username enumeration across social media platforms.

## Frequently Asked Questions

### Do I need API keys to run GhostTrack locally?

No, GhostTrack does not require API keys or authentication tokens. The IP Tracker uses the public `ipwho.is` endpoint, while the Phone Tracker and Username Tracker rely on open-source libraries and direct HTTP requests to public profile URLs. However, excessive requests to social media sites may trigger rate limiting.

### Can I run GhostTrack on Windows?

Yes, GhostTrack is cross-platform compatible. While the analysis shows Unix-style commands (`python3`, `clear()`), Windows users can run the tool by using `python GhostTR.py` instead of `python3`, provided Python is added to the system PATH. The `requests` and `phonenumbers` libraries work identically on Windows, macOS, and Linux.

### How do I exit the GhostTrack menu loop?

Select option **0** from the main menu or press **Ctrl+C** to interrupt the script execution. The `execute_option()` function includes logic to handle the exit selection, terminating the recursive `main()` loop and returning control to your terminal.

### What Python version is required for GhostTrack?

GhostTrack requires Python 3.x. The `phonenumbers` and `requests` libraries maintain compatibility with modern Python 3 versions. Python 2 is not supported due to syntax differences in the print functions and string handling used throughout [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py).