Skip to content

Instantly share code, notes, and snippets.

@JarbasAl

JarbasAl/install_tutorial.md

Last active March 27, 2025 17:51
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save JarbasAl/167b098f3ce0b1f9b4963c3082f04868 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save JarbasAl/167b098f3ce0b1f9b4963c3082f04868 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
install_tutorial.md

How to Install Open Voice OS with the ovos-installer

Welcome to the quick-start guide for installing Open Voice OS (OVOS) using the official ovos-installer! This guide is suitable for Raspberry Pi and desktop/server Linux environments. Whether you’re running this on a headless Raspberry Pi or your everyday laptop, the steps are mostly the same—only the way you connect to the device differs.

⚠️ Note: Some “exotic” hardware (like ReSpeaker microphones or certain audio HATs) may require extra configuration. The installer aims for wide compatibility, but specialized setups might need some manual intervention.

Looking for a pre-built raspberry pi image instead? check out raspOVOS and the companion tutorial

🚀 Step-by-step Installation

✅ 1. Connect to Your Device (if remote)

If you're installing on a headless device (like a Raspberry Pi), connect via SSH:

ssh -l your-username <your-device-ip>

🔄 2. Update Package Metadata

Make sure your package manager is up to date:

sudo apt update

📦 3. Install Prerequisites

Install git and curl—these are required to run the installer:

sudo apt install -y git curl

📥 4. Run the OVOS Installer

Now you're ready to kick off the installation process:

sudo sh -c "$(curl -fsSL https://raw.githubusercontent.com/OpenVoiceOS/ovos-installer/main/installer.sh)"

image

🧙 What Happens Next?

Once you run the script, the installer will:

  • Perform system checks
  • Install dependencies (Python, Ansible, etc.)
  • Launch a text-based user interface (TUI) to guide you through the setup

This can take anywhere from 5 to 20 minutes, depending on your hardware, internet speed, and storage performance. Now let’s walk through the installer screens!

🧩 The Installer Wizard

Navigation:

  • navigation is done via arrow keys
  • pressing space selects options in the lists
    • eg. when selecting virtualenv or containers
  • pressing tab will switch between the options and the <next>/<back> buttons
  • pressing enter will execute the highligted <next>/<back> option

🌍 Language Selection

The first screen lets you select your preferred language. Just follow the on-screen instructions.

image

🧠 Environment Summary

You’ll be shown a summary of the detected environment—no action needed here. It’s just informative.

image

🧰 Choose Installation Method

You have two choices:

  • Virtualenv: Recommended for most users. Easier to understand and manage.
  • Containers: For advanced users familiar with Docker or Podman.

image

🌱 Choose Channel

Select the “development” channel. Once OVOS is production-ready, a “stable” channel will also be available.

image

🧪 Choose Profile

Pick the ovos profile. This is the classic, all-in-one Open Voice OS experience with all the necessary components running locally.

image

🛠️ Feature Selection

Choose what features you’d like to install.

image

⚠️ Note: Some features (like the GUI) may be unavailable on lower-end hardware like the Raspberry Pi 3B+.

🍓 Raspberry Pi Tuning (if applicable)

On Raspberry Pi boards, you’ll be offered system tweaks to improve performance. It's highly recommended to enable this!

image

🧾 Summary

Before the installation begins, you'll see a summary of your selected options. This is your last chance to cancel the process.

image

📊 Anonymous Telemetry

You'll be asked whether to share anonymous usage data to help improve Open Voice OS. Please consider opting in!

image

The data collection only happens during the installation process, nothing else will be collected once the installation is over.

The installer will ask you if you want to share or not the data.

Below is a list of the collected data (please have a look to the Ansible tempalte used ti publish the data).

Data Description
architecture CPU architecture where OVOS was installed
channel stable or development version of OVOS
container OVOS installed into containers
country Country where OVOS has been installed
cpu_capable Is the CPU supports AVX2 or SIMD instructions
display_server Is X or Wayland are used as display server
extra_skills_feature Extra OVOS's skills enabled during the installation
gui_feature GUI enabled during the installation
hardware Is the device a Mark 1, Mark II or DevKit
installed_at Date when OVOS has been installed
os_kernel Kernel version of the host where OVOS is running
os_name OS name of the host where OVOS is running
os_type OS type of the host where OVOS is running
os_version OS version of the host where OVOS is running
profile Which profile has been used during the OVOS installation
python_version What Python version was running on the host
raspberry_pi Does OVOS has been installed on Raspberry Pi
skills_feature Default OVOS's skills enabled during the installation
sound_server What PulseAudio or PipeWire used
tuning_enabled Did the Rasperry Pi tuning feature wsas used
venv OVOS installed into a Python virtual environment

🧙‍♂️ Sit Back and Relax

The installation begins! This can take some time, so why not grab a coffee (or maybe a cupcake)? ☕🧁

Here is a demo of how the process should go if everything works as intended

asciicast

🎉 Installation Complete!

You’ve done it! OVOS is now installed and ready to serve you. Try saying things like:

  • “What’s the weather?”
  • “Tell me a joke.”
  • “Set a timer for 5 minutes.”

image

You’re officially part of the Open Voice OS community! 🎤✨

🛠️ Additional Configuration and Known Issues

Depending on your language you probably want to change the default plugins, the ovos-installer is not perfect and might not always select the best defaults

It is recommend that you run ovos-config autoconfigure --help after the initial install

asciicast

😱 Troubleshooting

Something went wrong?

Don’t panic! If the installer fails, it will generate a log file and upload it to https://dpaste.com. Please share that link with the community so we can help you out.

OVOS is a community-driven project, maintained by passionate volunteers. Your feedback, bug reports, and patience are truly appreciated.

📢 Language Support in OVOS Needs Your Help!

You can track the current translations status at https://openvoiceos.github.io/lang-support-tracker/

Your help with translations is invaluable!

You can find us on Gitlocalize, a text and video translation tutorial is available at https://www.openvoiceos.org/translation

🌍 How to Help?

we need real-world data to improve performance!

  • 🛠 Identify intent failures in daily usage
  • 🗣 Spot translation mistakes affecting accuracy
  • 📊 Improve models & pipelines

1️⃣ Enable Open Data Collection in your OVOS instance

  • Add this to your mycroft.conf:
"open_data": {
  "intent_urls": [
    "https://metrics.tigregotico.pt/intents"
  ]
}

(Or self-host to track your own assistant’s failed intents! 🔧 More info)

2️⃣ Monitor Progress & Data Collection:

OVOS is getting more users, but without native speakers contributing real data, accuracy will suffer!

Thanks for your help! Let’s make OVOS great for every language together! 🚀💙

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment