Installation

PadRelay can be installed in multiple ways depending on your use case.

System Requirements

Client Requirements

Python 3.6 or higher
pygame library
Any operating system (Windows, Linux, macOS)
A physical gamepad connected to your system

Server Requirements

Python 3.6 or higher
Windows operating system (for vgamepad support)
ViGEmBus driver installed
vgamepad library

Note

The server requires Windows because the vgamepad library uses ViGEmBus, which is Windows-only. The client can run on any platform.

Installation Methods

Method 1: Install from PyPI (Recommended)

The simplest way to install PadRelay is from PyPI:

pip install padrelay

This installs the base package with client dependencies. For server installation on Windows:

pip install padrelay[server]

This will install both padrelay and vgamepad with all necessary dependencies.

After installation, you’ll have three command-line tools available:

padrelay-client - Run the gamepad client
padrelay-server - Run the virtual gamepad server (Windows only)
padrelay-keymapper - Create custom controller mappings

Method 2: Install from Source

For development or to get the latest features:

git clone https://github.com/ssh-den/PadRelay.git
cd PadRelay
pip install -e .

For server installation with vgamepad:

pip install -e .[server]

Method 3: Install Dependencies Manually

If you prefer to manage dependencies yourself:

git clone https://github.com/ssh-den/PadRelay.git
cd PadRelay
pip install -r requirements.txt

Then install vgamepad on Windows:

pip install vgamepad

Installing ViGEmBus (Windows Server Only)

The server requires the ViGEmBus driver to create virtual gamepads on Windows.

Download the latest ViGEmBus installer from the releases page
Run the installer (ViGEmBusSetup_x64.msi or ViGEmBusSetup_x86.msi depending on your system)
Restart your computer after installation
Verify installation by checking Device Manager for “Nefarius Virtual Gamepad Emulation Bus”

Warning

ViGEmBus requires administrator privileges to install. Make sure to run the installer as administrator.

Optional Dependencies

TLS/SSL Support

For secure connections, TLS support is included by default via the cryptography package:

pip install cryptography>=41.0.0 cffi>=1.15.0

These are automatically installed with the base package.

Verifying Installation

To verify your installation:

Client Verification

padrelay-client --help

You should see the help message with all available options.

Server Verification (Windows)

padrelay-server --help

Key Mapper Verification

padrelay-keymapper --help

Testing Gamepad Detection

To test if your gamepad is detected:

import pygame
pygame.init()
pygame.joystick.init()
print(f"Number of joysticks: {pygame.joystick.get_count()}")
if pygame.joystick.get_count() > 0:
    joystick = pygame.joystick.Joystick(0)
    joystick.init()
    print(f"Joystick name: {joystick.get_name()}")
    print(f"Number of buttons: {joystick.get_numbuttons()}")

Upgrading

To upgrade to the latest version:

pip install --upgrade padrelay

Or for server installation:

pip install --upgrade padrelay[server]

Uninstallation

To uninstall PadRelay:

pip uninstall padrelay

Note

This does not uninstall ViGEmBus. To remove ViGEmBus, use the Windows “Add or Remove Programs” feature.

Troubleshooting Installation

Permission Errors

If you get permission errors during installation:

pip install --user padrelay

Or use a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install padrelay

vgamepad Installation Fails

If vgamepad fails to install, ensure you have:

Windows operating system
Visual C++ Build Tools installed
Latest version of pip: pip install --upgrade pip

pygame Installation Issues

On Linux, you may need additional dependencies:

# Ubuntu/Debian
sudo apt-get install python3-pygame

# Fedora
sudo dnf install python3-pygame

# Arch Linux
sudo pacman -S python-pygame

On macOS:

brew install pygame

Next Steps

After installation, proceed to the Quick Start Guide guide to set up and run your first gamepad relay session.