Skip to content

Latest commit



115 lines (74 loc) · 2.87 KB


File metadata and controls

115 lines (74 loc) · 2.87 KB

Getting started

This section will help you to quickly get started with SoCo.


SoCo can be installed either with :ref:`pip <installation_pip>` (recommended) or :ref:`manually <installation_manually>`.

From PyPI with pip

The easiest way to install SoCo, is to install it from PyPI with the program pip. This can be done with the command:

pip install soco

This will automatically take care of installing any dependencies you need.

Manual installation from .tar.gz file

SoCo can also be installed manually from the .tar.gz file. First, find the latest version of SoCo on PyPI and download the .tar.gz file at the bottom of the page. After that, extract the content and move into the extracted folder. As an example, for SoCo 0.11.1 and on a Unix type system, this can be done with the following commands:

tar zxvf soco-0.11.1.tar.gz
cd soco-0.11.1/

Have a look inside the requirements.txt file. You will need to install the dependencies listed in that file yourself. See the documentation for the individual dependencies for installation instructions.

After the requirements are in place, the package can be install with the command:

python install

After installation check

After installation, open a Python interpreter and check that :mod:`soco` can be imported and that your Sonos® players can be discovered:

>>> import soco
set([SoCo(""), SoCo(""), SoCo("")])


SoCo allows you to control your Sonos sound system from a Python program. For a quick start have a look at the example applications that come with the library.


For discovering the Sonos devices in your network, use :meth:``.

>>> import soco
>>> speakers =

It returns a :class:`set` of :class:`soco.SoCo` instances, each representing a speaker in your network.


You can use those SoCo instances to inspect and interact with your speakers.

>>> speaker = speakers.pop()
>>> speaker.player_name
'Living Room'
>>> speaker.ip_address

>>> speaker.volume
>>> speaker.volume = 15

See for :class:`soco.SoCo` for all methods that are available for a speaker.