Estimated reading time: 5 minutes

Mycroft for Linux

Mycroft is available for Linux, and can be installed via several methods.

Currently, there are builds and/or instructions for installing Mycroft on:

  • Debian / Ubuntu
  • Arch
  • Mint
  • KDE Plasmoid


This section of documentation assumes the following:

  • That you already have Linux installed on your computer
  • That your computer is already connected to the internet
  • That you are comfortable issuing basic Linux commands from a terminal or shell prompt
  • That your device has a built-in microphone and speakers, or, you have successfully connected microphone and speakers to your device.
  • That your device already has git installed and working. If you don't already have git installed, here is a great set of instructions.

@TODO do we need to comment here on whether bluetooth or USB is a better connection choice for headphones and speakers?

Getting Started

There are multiple ways to install Mycroft for Linux.

Installing via git clone

The simplest way to install Mycroft for Linux is to clone the mycroft-core repo to your system and run a shell script, which will install all dependencies, and Mycroft components.

The instructions below will install Mycroft in your HOME directory.

cd ~/
git clone
cd mycroft-core

The script identifies, installs and configures dependencies that Mycroft needs to run.

The script will also install and configure virtualenv. virtualenv is a tool to create isolated Python environments. It is a way to isolate an application - in this case Mycroft - from other applications. It helps to better manage both dependencies and security.

If you are running a Linux distribution other than Ubuntu, Debian, Arch or Fedora, you may need to manually install packages as instructed by

NOTE: The default branch for this repository is 'dev', which should be considered a work-in-progress. If you want to clone a more stable version, switch over to the 'master' branch.

You can do this by choosing the master branch in GitHub instead of the default dev branch as shown below.

Changing from the default dev branch to master on mycroft-core

Other installation options

@TODO what are the other installation options for Mycroft on Linux - there are the installers that @AIIX provided, and I think there's an apt-get package. Will need to clarify.

Running Mycroft for Linux

The Mycroft for Linux installation includes two scripts that you use to control Mycroft services. is used to start one, or all, Mycroft services. This script uses the virtualenv created by

The usage of is:

usage: [command] [params]

  all                      runs core services: bus, audio, skills, voice
  debug                    runs core services, then starts the CLI

  audio                    the audio playback service
  bus                      the messagebus service
  skills                   the skill service
  voice                    voice capture service
  wifi                     wifi setup service
  enclosure                mark_1 enclosure service

  cli                      the Command Line Interface
  unittest                 run mycroft-core unit tests

  skill_container <skill>  container for running a single skill
  audiotest                attempt simple audio validation
  audioaccuracytest        more complex audio validation
  sdkdoc                   generate sdk documentation

Examples: all cli unittest
To start all Mycroft services at once
$ ./ all
Starting all mycroft-core services
Starting background service bus
Starting background service skills
Starting background service audio
Starting background service voice
To start individual Mycroft services

Services can also be started individually.

$ ./ audio
Starting background service audio

Stopping Mycroft services

$ ./
Stopping all mycroft-core services

Pairing Mycroft for Linux

Once successfully installed, you will need to pair your Mycroft for Linux Device with your account.


Hey Mycroft, pair my device

Mycroft will Speak
"I am connected to the internet and need to be paired. Your 6-digit Registration Code is XXXXXX"

Use the Registration Code to pair your Mycroft for Linux Device with

View the documentation to learn how to add your Device to

Once paired, you can then use basic Skills.

Using Mycroft behind a proxy

Many schools, universities and workplaces run a proxy on their network. If you need to type in a username and password to access the external internet, then you are likely behind a proxy.

If you plan to use Mycroft behind a proxy, then you will need to do an additional configuration step.

NOTE: In order to complete this step, you will need to know the hostname and port for the proxy server. Your network administrator will be able to provide these details. Your network administrator may want information on what type of traffic Mycroft will be using. We use https traffic on port 443, primarily for accessing ReST-based APIs.

Using Mycroft behind a proxy without authentication

If you are using Mycroft behind a proxy without authentication, add the following environment variables, changing the and proxy_port for the values for your network. These commands are executed from the Linux command line interface (CLI).

$ export http_proxy=
$ export https_port=
$ export no_proxy="localhost,,localaddress,,,::1"

Using Mycroft behind an authenticated proxy

If you are behind a proxy which requires authentication, add the following environment variables, changing the and proxy_port for the values for your network. These commands are executed from the Linux command line interface (CLI).

$ export http_proxy=
$ export https_port=
$  export no_proxy="localhost,,localaddress,,,::1"

Keeping Mycroft for Linux updated

@TODO Not sure what the easiest way is to keep Mycroft for Linux updated - is it as simple as doing a git pull from the remote repo?

Removing Mycroft for Linux from your system

If you have installed mycroft-core using the git-clone method, then removing it requires a couple of steps.

NOTE: depending on your system, you may need to run the commands below with sudo

  • Remove the mycroft-core directory from wherever you installed it:

rm -R ~/yourpath/to/mycroft-core

  • Next, remove the Skills directories:

rm -R /opt/mycroft

  • Next, remove the Mycroft settings:

rm -R ~/.mycroft

  • Next, remove the virtualenv:

rm -R ~/.virtualenvs/mycroft

Common issues with Mycroft for Linux

Removing and rebuilding your virtualenv

If your CLI won't run, it is highly likely to be an issue with the Mycroft virtual environment. The easiest solution we've found has been to remove and reinstall the virtual environment.

First, delete the existing virtual environment:

sudo rm -R ~/.virtualenvs/mycroft

Next, we run the setup script again:

mycroft-core$ ./

This will rebuild your


Help us serve you better by rating this documentation