# NordVPN Switcher Pro
[](https://badge.fury.io/py/nordvpn-switcher-pro)
[](https://opensource.org/licenses/MIT)
**NordVPN Switcher Pro** is a powerful Python library for automating NordVPN server connections on Windows. It is designed for developers and automation engineers who need reliable, criteria-based IP rotation for tasks like web scraping, data collection, and application testing.
The library provides a simple interface to a complex process:
- It uses a **stable, current NordVPN API (verified working as of July 2025)**.
- It features a **one-time interactive setup** to configure your rotation rules.
- Once configured, your scripts can run **headlessly without any user input**.
- It intelligently **caches used servers** to avoid reconnecting to the same IP.
The core focus is providing robust control over the NordVPN client. It does not include unrelated functionality.
## Key Features
- **Interactive Setup**: A guided command-line interface to create your connection settings.
- **Criteria-Based Rotation**: Connect to servers by Country, Region, a custom list of countries (inclusion or exclusion), or special groups (e.g., P2P, Double VPN).
- **Smart Caching**: Remembers recently used servers and avoids them for a configurable duration (default: 24 hours).
- **Resilient**: Gracefully handles connection failures and automatically falls back to the least-recently-used server if all fresh options are exhausted.
- **Headless Operation**: After the initial setup, it runs without any prompts, making it perfect for automated scripts and servers.
- **Modular Design**: Built with a clear separation between the core logic and the Windows controller, making it possible for the community to add support for Linux or macOS in the future.
> **Note on Platform Support**
> Currently, **NordVPN Switcher Pro** officially supports **Windows only**, as it relies on the NordVPN for Windows command-line interface. The project is designed to be extensible, and contributions for a `LinuxVpnController` or `MacVpnController` are welcome!
## Installation
```bash
pip install nordvpn-switcher-pro
```
## Quick Start
The easiest way to get started is to let the interactive setup guide you. The first time you run your script, a settings file (`nordvpn_settings.json`) will be created based on your answers.
Here is a basic example of rotating your IP address three times:
```python
from nordvpn_switcher_pro import VpnSwitcher
import time
# 1. Initialize the switcher.
# If "nordvpn_settings.json" doesn't exist, it will launch an
# interactive setup in your terminal to create it.
switcher = VpnSwitcher()
try:
# 2. Start the session.
# This prepares the switcher, disconnects from any current VPN,
# and fetches the initial server list.
switcher.start_session()
for i in range(3):
# 3. Rotate to a new server based on your settings.
print(f"\n--- Rotation attempt {i+1} ---")
switcher.rotate()
# Do some work, e.g. scraping.
print("Waiting 15 seconds before the next rotation...")
time.sleep(15)
finally:
# 4. Terminate the session.
# This disconnects from the VPN and saves the updated server cache.
print("\nTerminating session.")
switcher.terminate()
```
## Connection Settings Explained
During the interactive setup, you'll be asked to define your rotation strategy. This involves two choices: **what** to connect to, and **how** servers are selected.
#### Connection Scope (What to connect to)
| Scope | Description |
| :--- | :--- |
| **Specific Country** | Rotates through servers in one or more specified countries. If multiple countries are given, it will exhaust all servers in the first country before moving to the next. |
| **Specific Region** | Connects to servers within a broad geographical region, like "The Americas" or "Europe". |
| **Custom Region (Include)** | Rotates only through servers in a custom list of countries you select. Ideal for targeting specific markets. |
| **Custom Region (Exclude)** | Rotates through servers in any country *except* for those in a custom list you provide. |
| **Worldwide** | Connects to any standard NordVPN server across the globe. |
| **Special Server Group** | Connects to a specific group like P2P, Double VPN, or Obfuscated. Since the app chooses the server, the switcher can be configured to retry if it gets a recently used IP. |
#### Server Selection Strategy (How to select)
- **Best available (recommended for IP rotation)**: Uses NordVPN's algorithm to find a server with the best combination of low latency (distance from you) and low load. This is ideal for quickly getting a new, high-performance IP.
- **Randomized by load (recommended for Geo rotation)**: Fetches *all* available servers for your chosen scope, groups them by load (0-20%, 20-30%, 30-40%, etc.), and picks a random server from the lowest-load bucket that still has unused servers. This provides greater server diversity.
## Visual Setup Examples
Here are a few GIFs demonstrating how to create different rotation strategies using the interactive setup.
<details>
<summary><strong>Example 1: Specific Countries (Germany & France)</strong></summary>
**Goal:** Create a rotation that uses servers first from Germany, then from France, using the fastest available servers in each.
**Configuration:**
- **Scope:** Specific Country
- **Countries:** Germany, France
- **Strategy:** Best available
</details>
<details>
<summary><strong>Example 2: Custom Region (DACH - Germany, Austria, Switzerland)</strong></summary>
**Goal:** Create a rotation that targets the German-speaking "DACH" region for specific geo-targeting.
**Configuration:**
- **Scope:** Custom Region (Include)
- **Countries:** Germany, Austria, Switzerland
- **Strategy:** Randomized by load (for greater server diversity within the region)
</details>
<details>
<summary><strong>Example 3: Worldwide Random</strong></summary>
**Goal:** Get a random IP address from any standard server in the world.
**Configuration:**
- **Scope:** Worldwide
- **Strategy:** Randomized by load
</details>
<details>
<summary><strong>Example 4: Special P2P Group</strong></summary>
**Goal:** Connect to NordVPN's optimized P2P server group.
**Configuration:**
- **Scope:** Special Server Group
- **Group:** P2P
</details>
## Advanced Usage
### Multiple Rotation Strategies
You can maintain multiple, independent rotation strategies by creating different `VpnSwitcher` instances, each with its own settings file. This is useful for complex workflows that require different geographic targets.
In this example, we'll simulate downloading region-locked videos from the US and Japan.
```python
from nordvpn_switcher_pro import VpnSwitcher
# A dummy function to represent our download logic
def download_video(video):
print(f"-> Downloading '{video['title']}'...")
# 1. Define the content to download, each with a region attribute.
videos_to_download = [
{'title': 'American Psycho (Unrated Cut)', 'region': 'us'},
{'title': 'Neon Genesis Evangelion (Remastered)', 'region': 'jp'},
{'title': 'The Matrix (Original 1999 Release)', 'region': 'us'},
]
# 2. Initialize a VPN switcher for each region
us_switcher = VpnSwitcher(settings_path="us_settings.json")
jp_switcher = VpnSwitcher(settings_path="jp_settings.json")
# 3. Start sessions for both
us_switcher.start_session()
jp_switcher.start_session()
# 4. Process the videos, switching IPs as needed
for video in videos_to_download:
region = video['region']
try:
if region == 'us':
us_switcher.rotate()
download_video(video)
elif region == 'jp':
jp_switcher.rotate()
download_video(video)
except Exception as e:
print(f"!! Error downloading '{video['title']}': {e}")
# 5. Terminate sessions and save caches
us_switcher.terminate()
jp_switcher.terminate()
print("\nAll tasks complete.")
```
### Manual Rotation Control
If you have selected the **Specific Country** scope, for more fine-grained control, you can manually trigger a switch to the next country in your list using `rotate(next_country=True)`.
This parameter forces the switcher to advance to the next country in your configured sequence, even if you haven't used all the servers in the current country.
> **Note**: This feature only works if you have configured the switcher with the **Specific Country** scope and provided more than one country ID during setup.
#### Example: Forcing a Country Switch
Imagine you need to process 5 tasks in Germany, then immediately switch to France for the next 5 tasks.
```python
from nordvpn_switcher_pro import VpnSwitcher
# Assume this switcher was configured with Germany then France.
switcher = VpnSwitcher(settings_path='de_fr_settings.json')
switcher.start_session()
try:
# --- Process Germany Tasks ---
for i in range(5):
switcher.rotate()
print(f"Processing Germany task {i+1}...")
# --- Manually switch to France for the next set of tasks ---
print("\nFinished Germany tasks. Forcing switch to next country...")
switcher.rotate(next_country=True)
# --- Process France Tasks ---
for i in range(5):
# We don't need next_country=True here anymore
switcher.rotate()
print(f"Processing France task {i+1}...")
finally:
switcher.terminate()
```
## How It Works
The library is composed of a few key components:
- `VpnSwitcher`: The main class that orchestrates the entire process.
- `WindowsVpnController`: A dedicated module that interacts with the `NordVPN.exe` command-line interface.
- `NordVpnApiClient`: A client that communicates with the public NordVPN API to fetch server lists and data.
- `RotationSettings`: A data class for saving and loading your configuration and server cache.
## Disclaimer
This project is an unofficial tool and is not affiliated with, endorsed by, or sponsored by NordVPN or Tefincom S.A. It is a personal project intended for educational and research purposes. Use it at your own risk.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/Sebastian7700/nordvpn-switcher-pro",
"name": "nordvpn-switcher-pro",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "nordvpn vpn switcher automation web-scraping ip-rotation rotate-ip windows api",
"author": "Sebastian Hanisch",
"author_email": "contact.sebastian.hanisch@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/3a/b5/0997152587d69572500dad9ea667e31eb931905dc1cc08671953d8c88579/nordvpn_switcher_pro-1.0.2.tar.gz",
"platform": null,
"description": "# NordVPN Switcher Pro\r\n\r\n[](https://badge.fury.io/py/nordvpn-switcher-pro)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\n\r\n\r\n**NordVPN Switcher Pro** is a powerful Python library for automating NordVPN server connections on Windows. It is designed for developers and automation engineers who need reliable, criteria-based IP rotation for tasks like web scraping, data collection, and application testing.\r\n\r\nThe library provides a simple interface to a complex process:\r\n- It uses a **stable, current NordVPN API (verified working as of July 2025)**.\r\n- It features a **one-time interactive setup** to configure your rotation rules.\r\n- Once configured, your scripts can run **headlessly without any user input**.\r\n- It intelligently **caches used servers** to avoid reconnecting to the same IP.\r\n\r\nThe core focus is providing robust control over the NordVPN client. It does not include unrelated functionality.\r\n\r\n## Key Features\r\n\r\n- **Interactive Setup**: A guided command-line interface to create your connection settings.\r\n- **Criteria-Based Rotation**: Connect to servers by Country, Region, a custom list of countries (inclusion or exclusion), or special groups (e.g., P2P, Double VPN).\r\n- **Smart Caching**: Remembers recently used servers and avoids them for a configurable duration (default: 24 hours).\r\n- **Resilient**: Gracefully handles connection failures and automatically falls back to the least-recently-used server if all fresh options are exhausted.\r\n- **Headless Operation**: After the initial setup, it runs without any prompts, making it perfect for automated scripts and servers.\r\n- **Modular Design**: Built with a clear separation between the core logic and the Windows controller, making it possible for the community to add support for Linux or macOS in the future.\r\n\r\n> **Note on Platform Support**\r\n> Currently, **NordVPN Switcher Pro** officially supports **Windows only**, as it relies on the NordVPN for Windows command-line interface. The project is designed to be extensible, and contributions for a `LinuxVpnController` or `MacVpnController` are welcome!\r\n\r\n## Installation\r\n\r\n```bash\r\npip install nordvpn-switcher-pro\r\n```\r\n\r\n## Quick Start\r\n\r\nThe easiest way to get started is to let the interactive setup guide you. The first time you run your script, a settings file (`nordvpn_settings.json`) will be created based on your answers.\r\n\r\nHere is a basic example of rotating your IP address three times:\r\n\r\n```python\r\nfrom nordvpn_switcher_pro import VpnSwitcher\r\nimport time\r\n\r\n# 1. Initialize the switcher.\r\n# If \"nordvpn_settings.json\" doesn't exist, it will launch an\r\n# interactive setup in your terminal to create it.\r\nswitcher = VpnSwitcher()\r\n\r\ntry:\r\n # 2. Start the session.\r\n # This prepares the switcher, disconnects from any current VPN,\r\n # and fetches the initial server list.\r\n switcher.start_session()\r\n\r\n for i in range(3):\r\n # 3. Rotate to a new server based on your settings.\r\n print(f\"\\n--- Rotation attempt {i+1} ---\")\r\n switcher.rotate()\r\n\r\n # Do some work, e.g. scraping.\r\n print(\"Waiting 15 seconds before the next rotation...\")\r\n time.sleep(15)\r\n\r\nfinally:\r\n # 4. Terminate the session.\r\n # This disconnects from the VPN and saves the updated server cache.\r\n print(\"\\nTerminating session.\")\r\n switcher.terminate()\r\n```\r\n\r\n## Connection Settings Explained\r\n\r\nDuring the interactive setup, you'll be asked to define your rotation strategy. This involves two choices: **what** to connect to, and **how** servers are selected.\r\n\r\n#### Connection Scope (What to connect to)\r\n\r\n| Scope | Description |\r\n| :--- | :--- |\r\n| **Specific Country** | Rotates through servers in one or more specified countries. If multiple countries are given, it will exhaust all servers in the first country before moving to the next. |\r\n| **Specific Region** | Connects to servers within a broad geographical region, like \"The Americas\" or \"Europe\". |\r\n| **Custom Region (Include)** | Rotates only through servers in a custom list of countries you select. Ideal for targeting specific markets. |\r\n| **Custom Region (Exclude)** | Rotates through servers in any country *except* for those in a custom list you provide. |\r\n| **Worldwide** | Connects to any standard NordVPN server across the globe. |\r\n| **Special Server Group** | Connects to a specific group like P2P, Double VPN, or Obfuscated. Since the app chooses the server, the switcher can be configured to retry if it gets a recently used IP. |\r\n\r\n#### Server Selection Strategy (How to select)\r\n\r\n- **Best available (recommended for IP rotation)**: Uses NordVPN's algorithm to find a server with the best combination of low latency (distance from you) and low load. This is ideal for quickly getting a new, high-performance IP.\r\n- **Randomized by load (recommended for Geo rotation)**: Fetches *all* available servers for your chosen scope, groups them by load (0-20%, 20-30%, 30-40%, etc.), and picks a random server from the lowest-load bucket that still has unused servers. This provides greater server diversity.\r\n\r\n## Visual Setup Examples\r\n\r\nHere are a few GIFs demonstrating how to create different rotation strategies using the interactive setup.\r\n\r\n<details>\r\n<summary><strong>Example 1: Specific Countries (Germany & France)</strong></summary>\r\n\r\n**Goal:** Create a rotation that uses servers first from Germany, then from France, using the fastest available servers in each.\r\n\r\n**Configuration:**\r\n- **Scope:** Specific Country\r\n- **Countries:** Germany, France\r\n- **Strategy:** Best available\r\n\r\n\r\n\r\n</details>\r\n\r\n<details>\r\n<summary><strong>Example 2: Custom Region (DACH - Germany, Austria, Switzerland)</strong></summary>\r\n\r\n**Goal:** Create a rotation that targets the German-speaking \"DACH\" region for specific geo-targeting.\r\n\r\n**Configuration:**\r\n- **Scope:** Custom Region (Include)\r\n- **Countries:** Germany, Austria, Switzerland\r\n- **Strategy:** Randomized by load (for greater server diversity within the region)\r\n\r\n\r\n\r\n</details>\r\n\r\n<details>\r\n<summary><strong>Example 3: Worldwide Random</strong></summary>\r\n\r\n**Goal:** Get a random IP address from any standard server in the world.\r\n\r\n**Configuration:**\r\n- **Scope:** Worldwide\r\n- **Strategy:** Randomized by load\r\n\r\n\r\n\r\n</details>\r\n\r\n<details>\r\n<summary><strong>Example 4: Special P2P Group</strong></summary>\r\n\r\n**Goal:** Connect to NordVPN's optimized P2P server group.\r\n\r\n**Configuration:**\r\n- **Scope:** Special Server Group\r\n- **Group:** P2P\r\n\r\n\r\n\r\n</details>\r\n\r\n## Advanced Usage\r\n\r\n### Multiple Rotation Strategies\r\n\r\nYou can maintain multiple, independent rotation strategies by creating different `VpnSwitcher` instances, each with its own settings file. This is useful for complex workflows that require different geographic targets.\r\n\r\nIn this example, we'll simulate downloading region-locked videos from the US and Japan.\r\n\r\n```python\r\nfrom nordvpn_switcher_pro import VpnSwitcher\r\n\r\n# A dummy function to represent our download logic\r\ndef download_video(video):\r\n print(f\"-> Downloading '{video['title']}'...\")\r\n\r\n# 1. Define the content to download, each with a region attribute.\r\nvideos_to_download = [\r\n {'title': 'American Psycho (Unrated Cut)', 'region': 'us'},\r\n {'title': 'Neon Genesis Evangelion (Remastered)', 'region': 'jp'},\r\n {'title': 'The Matrix (Original 1999 Release)', 'region': 'us'},\r\n]\r\n\r\n# 2. Initialize a VPN switcher for each region\r\nus_switcher = VpnSwitcher(settings_path=\"us_settings.json\")\r\njp_switcher = VpnSwitcher(settings_path=\"jp_settings.json\")\r\n\r\n# 3. Start sessions for both\r\nus_switcher.start_session()\r\njp_switcher.start_session()\r\n\r\n# 4. Process the videos, switching IPs as needed\r\nfor video in videos_to_download:\r\n region = video['region']\r\n \r\n try:\r\n if region == 'us':\r\n us_switcher.rotate()\r\n download_video(video)\r\n elif region == 'jp':\r\n jp_switcher.rotate()\r\n download_video(video)\r\n\r\n except Exception as e:\r\n print(f\"!! Error downloading '{video['title']}': {e}\")\r\n\r\n# 5. Terminate sessions and save caches\r\nus_switcher.terminate()\r\njp_switcher.terminate()\r\n\r\nprint(\"\\nAll tasks complete.\")\r\n\r\n```\r\n\r\n### Manual Rotation Control\r\n\r\nIf you have selected the **Specific Country** scope, for more fine-grained control, you can manually trigger a switch to the next country in your list using `rotate(next_country=True)`.\r\n\r\nThis parameter forces the switcher to advance to the next country in your configured sequence, even if you haven't used all the servers in the current country.\r\n\r\n> **Note**: This feature only works if you have configured the switcher with the **Specific Country** scope and provided more than one country ID during setup.\r\n\r\n#### Example: Forcing a Country Switch\r\n\r\nImagine you need to process 5 tasks in Germany, then immediately switch to France for the next 5 tasks.\r\n\r\n```python\r\nfrom nordvpn_switcher_pro import VpnSwitcher\r\n\r\n# Assume this switcher was configured with Germany then France.\r\nswitcher = VpnSwitcher(settings_path='de_fr_settings.json')\r\nswitcher.start_session()\r\n\r\ntry:\r\n # --- Process Germany Tasks ---\r\n for i in range(5):\r\n switcher.rotate()\r\n print(f\"Processing Germany task {i+1}...\")\r\n\r\n # --- Manually switch to France for the next set of tasks ---\r\n print(\"\\nFinished Germany tasks. Forcing switch to next country...\")\r\n switcher.rotate(next_country=True)\r\n \r\n # --- Process France Tasks ---\r\n for i in range(5):\r\n # We don't need next_country=True here anymore\r\n switcher.rotate()\r\n print(f\"Processing France task {i+1}...\")\r\n\r\nfinally:\r\n switcher.terminate()\r\n```\r\n\r\n## How It Works\r\n\r\nThe library is composed of a few key components:\r\n- `VpnSwitcher`: The main class that orchestrates the entire process.\r\n- `WindowsVpnController`: A dedicated module that interacts with the `NordVPN.exe` command-line interface.\r\n- `NordVpnApiClient`: A client that communicates with the public NordVPN API to fetch server lists and data.\r\n- `RotationSettings`: A data class for saving and loading your configuration and server cache.\r\n\r\n## Disclaimer\r\n\r\nThis project is an unofficial tool and is not affiliated with, endorsed by, or sponsored by NordVPN or Tefincom S.A. It is a personal project intended for educational and research purposes. Use it at your own risk.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "An advanced Python library to automate NordVPN server switching on Windows.",
"version": "1.0.2",
"project_urls": {
"Bug Reports": "https://github.com/Sebastian7700/nordvpn-switcher-pro/issues",
"Homepage": "https://github.com/Sebastian7700/nordvpn-switcher-pro",
"Source": "https://github.com/Sebastian7700/nordvpn-switcher-pro/"
},
"split_keywords": [
"nordvpn",
"vpn",
"switcher",
"automation",
"web-scraping",
"ip-rotation",
"rotate-ip",
"windows",
"api"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "11fa536d990d487b0acb1be195fce70af39fc0b98bbe20865fcdb776d202699a",
"md5": "6fc5ebde42ca5098bd42cec5305796ac",
"sha256": "8c356f870c5c443b1ab2c67fe4deb22b10bffa152b29669a165bb1c3f6f67e5c"
},
"downloads": -1,
"filename": "nordvpn_switcher_pro-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6fc5ebde42ca5098bd42cec5305796ac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 25997,
"upload_time": "2025-07-23T15:24:20",
"upload_time_iso_8601": "2025-07-23T15:24:20.647229Z",
"url": "https://files.pythonhosted.org/packages/11/fa/536d990d487b0acb1be195fce70af39fc0b98bbe20865fcdb776d202699a/nordvpn_switcher_pro-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3ab50997152587d69572500dad9ea667e31eb931905dc1cc08671953d8c88579",
"md5": "1654a08a69d2572f9034463cbfc4b497",
"sha256": "cf629a10609b182a7aea9df0ac1318543d74618218a332baec58882198d411e3"
},
"downloads": -1,
"filename": "nordvpn_switcher_pro-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "1654a08a69d2572f9034463cbfc4b497",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 27624,
"upload_time": "2025-07-23T15:24:21",
"upload_time_iso_8601": "2025-07-23T15:24:21.756022Z",
"url": "https://files.pythonhosted.org/packages/3a/b5/0997152587d69572500dad9ea667e31eb931905dc1cc08671953d8c88579/nordvpn_switcher_pro-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 15:24:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Sebastian7700",
"github_project": "nordvpn-switcher-pro",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "nordvpn-switcher-pro"
}
JSON
