voice-mode-install
A standalone installer package for VoiceMode that handles system dependency detection and installation.
Overview
voice-mode-install simplifies the VoiceMode installation process by:
- Detecting your platform - Identifies your OS, distribution, and architecture
- Checking dependencies - Scans for required system packages
- Installing packages - Uses your system's package manager (apt, dnf, brew)
- Installing VoiceMode - Runs
uv tool install voice-mode - Hardware recommendations - Suggests optimal configuration for your system
- Logging everything - Saves installation logs for troubleshooting
Quick Start
# Install and run
uvx voice-mode-install
# Dry run (see what would be installed)
uvx voice-mode-install --dry-run
# Install specific version
uvx voice-mode-install --voice-mode-version=5.1.3
# Skip service installation
uvx voice-mode-install --skip-services
# Non-interactive mode
uvx voice-mode-install --non-interactive
Prerequisites
- uv - Required to run the installer (
curl -LsSf https://astral.sh/uv/install.sh | sh) - Python 3.10+ - Usually pre-installed on modern systems
- sudo access - Needed to install system packages (Linux)
- Homebrew (macOS) - The installer will offer to install it if missing
Supported Platforms
- macOS - Intel and Apple Silicon (via Homebrew)
- Ubuntu/Debian - Using apt package manager
- Fedora/RHEL - Using dnf package manager
Features
Phase 1 (Included)
✅ Dry-run Mode - Preview what will be installed
✅ Installation Logging - Detailed logs saved to ~/.voicemode/install.log
✅ Shell Completion - Auto-configures tab completion for bash/zsh
✅ Health Check - Verifies installation after completion
✅ Version Pinning - Install specific VoiceMode versions
✅ Hardware Detection - Recommends optimal setup for your system
✅ Homebrew Auto-Install - Offers to install Homebrew on macOS if missing
Phase 2 (Future)
⏱️ Config Validation - Check for conflicting settings ⏱️ Uninstall Support - Clean removal of VoiceMode
How It Works
- Platform Detection - Identifies OS, distribution, and architecture
- Dependency Checking - Compares installed packages against
dependencies.yaml - Package Manager Setup (macOS only) - Checks for Homebrew and offers to install if missing
- Package Installation - Uses platform-specific package managers:
- macOS:
brew install(installs Homebrew first if needed) - Ubuntu/Debian:
sudo apt install - Fedora:
sudo dnf install
- macOS:
- VoiceMode Installation - Runs
uv tool install voice-mode[==version] - Post-Install - Configures shell completion and verifies installation
Installation Logs
Logs are saved to ~/.voicemode/install.log in JSONL format:
{"timestamp": "2025-10-12T10:30:00", "type": "start", "message": "Installation started"}
{"timestamp": "2025-10-12T10:30:15", "type": "check", "message": "Checked core dependencies"}
{"timestamp": "2025-10-12T10:30:45", "type": "install", "message": "Successfully installed system packages"}
{"timestamp": "2025-10-12T10:31:30", "type": "complete", "message": "Installation completed"}
Troubleshooting
VoiceMode command not found after installation
Restart your shell or run:
source ~/.bashrc # or ~/.zshrc for zsh
Permission denied during package installation
The installer needs sudo access to install system packages. Run:
sudo -v # Refresh sudo credentials
uvx voice-mode-install
Network errors during installation
- Check your internet connection
- Try again with:
uvx voice-mode-install - Use
uvx --refresh voice-mode-installto get the latest installer
Installation hangs or fails
- Check the log file:
~/.voicemode/install.log - Try a dry run:
uvx voice-mode-install --dry-run - Report issues with log file attached
Development
Building from Source
cd installer/
uv build
Testing Locally
cd installer/
uv pip install -e .
voice-mode-install --dry-run
Project Structure
installer/
├── pyproject.toml # Package definition
├── voicemode_install/
│ ├── __init__.py # Version and exports
│ ├── cli.py # Main CLI entry point
│ ├── system.py # Platform detection
│ ├── checker.py # Dependency checking
│ ├── installer.py # Package installation
│ ├── hardware.py # Hardware detection
│ ├── logger.py # Installation logging
│ └── dependencies.yaml # System dependencies
└── README.md
Design Decisions
See DECISIONS.md in the task directory for detailed rationale behind:
- Version management strategy
- Dependency synchronization approach
- Error handling philosophy
- Platform coverage priorities
- Service installation scope
Contributing
This installer is part of the VoiceMode project.
License
MIT License - Same as VoiceMode
1 maintainer
Metadata
1 maintainer
Release files for voice-mode-install 9.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| voice_mode_install-9.0.1.tar.gz | 16.4 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| voice_mode_install-9.0.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 35.5 kB
Release files / voice_mode_install-9.0.1.tar.gz
| Download URL | voice_mode_install-9.0.1.tar.gz |
|---|---|
| Size | 16.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1266c405f1a21d3807e7d350507e097aa88b6ff75bf532f2cd6678de378e2fca
|
|
BLAKE2b-256 checksum How to use checksums |
4e28c438406decb2b92c0f815b0ab458325e467aaf4c2f67fe2a52aa94b16c9d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / voice_mode_install-9.0.1-py3-none-any.whl
| Download URL | voice_mode_install-9.0.1-py3-none-any.whl |
|---|---|
| Size | 19.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
48ae2668b172d94da5dd83573c4620dd6aa1c5c9815a7b03614753c43c31d491
|
|
BLAKE2b-256 checksum How to use checksums |
101557fbe661bebe71c3e216fb273bbd0015c0ec1fc5e6f2d6f27123f94aa3de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logSecurity for voice-mode-install 9.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for voice_mode_install-9.0.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
