# How Voice-Pro Handles GPU or CPU Selection: Device Detection and Configuration

> Learn how Voice-Pro selects GPU or CPU using its three-tier detection system. Discover device detection and configuration for optimal performance.

- Repository: [ABUS/voice-pro](https://github.com/abus-aikorea/voice-pro)
- Tags: internals
- Published: 2026-08-03

---

**Voice-Pro determines whether to use GPU or CPU through a three-tier detection system in [`app/one_click.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/one_click.py) that prioritizes the `GPU_CHOICE` environment variable, falls back to a persisted [`installer_files/gpu_choice.txt`](https://github.com/abus-aikorea/voice-pro/blob/main/installer_files/gpu_choice.txt) file, and defaults to CPU if neither is present.**

Voice-Pro, an open-source voice processing toolkit maintained by abus-aikorea, implements a deterministic bootstrap mechanism to select between CUDA GPU acceleration and CPU execution. Understanding how Voice-Pro handles GPU or CPU selection is critical for ensuring the correct PyTorch binaries are installed and that downstream modules target the appropriate compute device. The selection logic resides in the `OneClick` helper class and influences both the dependency resolution phase and runtime model allocation.

## The Three-Tier Detection Hierarchy

Voice-Pro's device selection follows a priority cascade defined in the `OneClick.gpu_choice()` class method within [`app/one_click.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/one_click.py). This hierarchy allows users to override persisted settings via environment variables while maintaining defaults across application restarts.

### Environment Variable Override

The system first inspects the `GPU_CHOICE` environment variable at startup. Valid values are `"G"` for GPU or `"C"` for CPU. When this variable is set, it takes precedence over all other configuration sources, enabling temporary overrides without modifying persisted files.

### Persisted Configuration File

If `GPU_CHOICE` is unset or empty, the code looks for [`installer_files/gpu_choice.txt`](https://github.com/abus-aikorea/voice-pro/blob/main/installer_files/gpu_choice.txt) inside the installation directory. This file is written by the start and update scripts (`start.bat` or [`start.sh`](https://github.com/abus-aikorea/voice-pro/blob/main/start.sh)) during initial setup. The content (`G` or `C`) is read and normalized to uppercase to determine the compute preference.

### CPU Default Fallback

When neither the environment variable nor the persisted file yields a valid value, the method returns `"C"`, forcing CPU execution. This conservative default ensures the application remains functional on systems without CUDA-capable hardware.

```python

# https://github.com/abus-aikorea/voice-pro/blob/main/one_click.py#L60-L68

def gpu_choice(cls):
    # GPU_CHOICE env var > choice saved by start/update scripts > CPU

    choice = os.environ.get("GPU_CHOICE", "").upper()
    if not choice:
        saved = os.path.join(cls.install_dir, "gpu_choice.txt")
        if os.path.exists(saved):
            choice = open(saved).read().strip().upper()
    return choice if choice in ("G", "C") else "C"

```

## Applying the Selection: Installation and Runtime

The value returned by `gpu_choice()` drives two distinct behaviors that occur at different stages of the application lifecycle.

### UV Dependency Resolution

During environment installation or updates, Voice-Pro uses **UV** (the Python package installer) to synchronize dependencies. The device selection determines which **optional dependency group** (extra) is passed to the sync command. The [`pyproject.toml`](https://github.com/abus-aikorea/voice-pro/blob/main/pyproject.toml) defines separate `gpu` and `cpu` extras that control whether CUDA-enabled PyTorch wheels are installed.

```python

# https://github.com/abus-aikorea/voice-pro/blob/main/one_click.py#L160-L169

extra = "gpu" if cls.gpu_choice() == "G" else "cpu"
uv = cls.uv_exe()
cls.oc_run_cmd(f'"{uv}" sync --frozen --extra {extra}', assert_success=True)

```

When `"gpu"` is selected, UV installs CUDA-compiled PyTorch binaries required for GPU acceleration. The `"cpu"` extra installs CPU-only wheels, reducing installation size on systems without compatible NVIDIA hardware.

### Runtime Device Allocation

Throughout Voice-Pro's core modules—including ASR (Automatic Speech Recognition), TTS (Text-to-Speech), and translation—the code relies on PyTorch's device management. When `GPU_CHOICE` is `"G"`, the application assumes CUDA availability (verified via `torch.cuda.is_available()`) and explicitly moves models to the `"cuda"` device. Because the appropriate PyTorch package was installed during the UV sync phase, runtime code can safely assume GPU availability when the selection is `"G"`.

## Practical Configuration Examples

Users can control Voice-Pro's compute device through several methods depending on their workflow requirements.

### Forcing GPU Usage

Set the environment variable before launching the application:

```bash
export GPU_CHOICE=G  # Linux/macOS

# OR

set GPU_CHOICE=G     # Windows CMD

# Then start

start.bat

```

### Forcing CPU Usage

Explicitly disable GPU acceleration to avoid CUDA initialization:

```bash
export GPU_CHOICE=C
start.bat

```

### Using Persisted Settings

Allow the start scripts to read from [`installer_files/gpu_choice.txt`](https://github.com/abus-aikorea/voice-pro/blob/main/installer_files/gpu_choice.txt) by omitting the environment variable:

```bash

# Ensure installer_files/gpu_choice.txt contains G or C

unset GPU_CHOICE
start.bat

```

## Summary

- **Detection Order**: Voice-Pro checks `GPU_CHOICE` environment variable first, then [`installer_files/gpu_choice.txt`](https://github.com/abus-aikorea/voice-pro/blob/main/installer_files/gpu_choice.txt), and defaults to CPU (`"C"`).
- **Installation Impact**: The selection determines whether UV installs `gpu` or `cpu` extras from [`pyproject.toml`](https://github.com/abus-aikorea/voice-pro/blob/main/pyproject.toml), controlling PyTorch wheel variants.
- **Runtime Behavior**: Downstream modules use the selection to target PyTorch devices, with `"G"` enabling CUDA model placement.
- **Configuration Location**: Core logic resides in [`app/one_click.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/one_click.py) within the `OneClick.gpu_choice()` method (lines 60-68).

## Frequently Asked Questions

### How do I permanently set Voice-Pro to use GPU?

Write `G` to the [`installer_files/gpu_choice.txt`](https://github.com/abus-aikorea/voice-pro/blob/main/installer_files/gpu_choice.txt) file in your Voice-Pro installation directory. This persists the preference across restarts without requiring environment variables. Alternatively, run the start scripts once with `GPU_CHOICE=G` exported, which typically writes this value to the file automatically.

### What happens if I set GPU_CHOICE to an invalid value?

Invalid values (anything other than `"G"` or `"C"`) cause the `gpu_choice()` method to return `"C"`, forcing CPU mode. This safety mechanism prevents startup failures due to typos or unsupported device codes.

### Why does Voice-Pro use UV extras instead of runtime detection?

Using UV extras during installation ensures only the necessary PyTorch binaries are downloaded. GPU wheels include large CUDA libraries (several gigabytes), while CPU wheels are significantly smaller. This approach optimizes disk usage and installation time based on the target hardware.

### Can I switch from GPU to CPU without reinstalling?

Yes. Change the `GPU_CHOICE` environment variable to `"C"` and restart the application. However, if the underlying PyTorch packages were installed for GPU, you may need to run the update scripts to sync CPU-only dependencies via `uv sync --extra cpu` to avoid CUDA runtime errors.