Installation¶
Choose one installation method. You do not need both Python and Docker.
PyPI is usually the easiest local option. If you are new to Python or unsure whether Python is ready, follow New to Python: check and install.
The direct Docker image is the fastest container option. Docker Compose takes one extra download but gives you shorter commands for later runs.
Requirements¶
Choose either the Python path or the container path.
Python path:
- Python 3.9 or higher
- Core libraries:
requests,python-dateutil,urllib3,pyotp,python-dotenv,wcwidth - spotipy is optional and is needed only for legacy OAuth metadata access
- pycookiecheat is optional and is needed only to import cookies from Chrome, Brave or Chromium
- Pillow is optional and is needed only to attach playlist and album artwork to ntfy alerts
- colorama is optional and improves coloured output in the classic Windows Command Prompt.
--doctorreports it as missing only on Windows, where it makes a difference
Container path (Python is included in the image):
- Any Docker-compatible runtime such as:
- Docker Desktop (macOS, Windows, Linux)
- Docker Engine (Linux)
- Colima with Docker CLI (macOS)
- OrbStack (macOS)
- Rancher Desktop with Moby or Docker CLI enabled (macOS, Windows, Linux)
- The Docker Compose v2 plugin if you choose the Compose method
The published image already contains Python and all core libraries. You do not need a local Python installation for Docker.
The examples use the docker command. Check that it works with docker --version. If you choose Compose, also check docker compose version.
Tested on:
- macOS: Tahoe, Sequoia, Sonoma, Ventura
- Linux: Raspberry Pi OS (Trixie, Bookworm, Bullseye), Ubuntu 24/25, Rocky Linux 8.x/9.x, Kali Linux 2026/2025/2024
- Windows: 11, 10
It should work on other versions of macOS, Linux, Unix and Windows as well.
New to Python: check and install¶
Use this section if you are new to Python or do not know what is already installed. The platform sections only prepare Python and pip. Everyone then uses the same Spotify Monitor installation and setup commands. Spotify Monitor requires Python 3.9 or newer and is currently tested through Python 3.14.
Check whether Spotify Monitor is already installed¶
Open Windows PowerShell on Windows or Terminal on macOS and Linux then run:
spotify_monitor --version
If this prints a Spotify Monitor version, skip to Run the setup wizard. If the command is not recognized or not found, continue with the section for your operating system.
Windows 10 or 11¶
Open Windows PowerShell. Select Start, type PowerShell then open Windows PowerShell.
Check Python and pip:
python --version
pip --version
If both commands work and Python reports version 3.9 or newer, skip to Install Spotify Monitor.
If either command fails:
-
Open the official Python Install Manager in Microsoft Store, select View in Store then select Install. If Microsoft Store is unavailable, download the manager from python.org.
-
Close PowerShell then open it again.
-
Run
python --version. Python Install Manager downloads the current Python release if no runtime is installed. -
Check both commands again:
python --version pip --version
If pip is still not recognized, run py install --refresh, close PowerShell then open it again. py install belongs to Python Install Manager and is used only to repair its Python commands.
See the official Python Install Manager troubleshooting table if either check is still unavailable.
macOS¶
Open Terminal. Press Command+Space, type Terminal then press Return.
Check Python and pip:
python3 --version
pip --version
If both commands work and Python reports version 3.9 or newer, skip to Install Spotify Monitor.
If either command fails:
-
Open the official Python downloads for macOS. Select the latest stable Python 3.14 release then download its macOS 64-bit universal2 installer. This single installer supports Apple Silicon and Intel Macs.
-
Open the downloaded
.pkgfile. Keep the standard options, select Continue through the installer then enter your macOS password when requested. -
Open the new Python 3.14 folder in Applications then double-click Install Certificates.command. Wait until its Terminal window reports
update completethen close that window. -
Close Terminal then open it again.
-
Check both commands again:
python3 --version pip --version
The official Using Python on macOS guide shows every installer screen and explains the installed applications.
Ubuntu, Debian, Raspberry Pi OS or Kali¶
Open Terminal then check Python and pip:
python3 --version
pip --version
If both commands work and Python reports version 3.9 or newer, skip to Install Spotify Monitor.
If either command fails, install the missing packages:
sudo apt update
sudo apt install python3 python3-pip
The package manager keeps an existing current package instead of reinstalling it. Terminal may ask for your password. Type the password you use to sign in then press Enter. Terminal does not show password characters while you type.
Check both commands again:
python3 --version
pip --version
If Python reports a version older than 3.9, follow your distribution's instructions to install a supported Python version before continuing. For another Linux distribution, install Python 3.9 or newer plus pip through its package manager.
Install Spotify Monitor¶
Every operating system uses the same command:
pip install spotify_monitor
Verify the installation:
spotify_monitor --version
On Linux, pip may report that the system Python is externally managed. If that happens, install Spotify Monitor with the isolated pipx tool instead:
sudo apt install pipx
pipx ensurepath
pipx install spotify_monitor
Close Terminal, open it again then run spotify_monitor --version.
Run the setup wizard¶
Every operating system uses the same command:
spotify_monitor --setup
The setup wizard can import a signed-in Firefox session, save the target and configure notifications. Continue to Setup & First Run for a walkthrough of its questions.
Choose an Installation Method¶
| Method | Best for | Command used in later examples |
|---|---|---|
| PyPI | Local users who already have Python or followed the beginner steps above | spotify_monitor [OPTIONS] |
| Manual script | Users who want to download and run one Python file | python3 spotify_monitor.py [OPTIONS] on macOS/Linux or python spotify_monitor.py [OPTIONS] on Windows |
| Docker Hub image | Users who want the fastest container setup | docker run ... misiektoja/spotify-monitor:latest [OPTIONS] |
| Docker Compose | Users who prefer shorter recurring commands after setup | docker compose run --rm spotify_monitor [OPTIONS] |
Later pages use the short PyPI command unless Docker behaves differently. If you chose another method, keep the options after spotify_monitor but replace spotify_monitor with the command in the table. The setup wizard and --help also print commands for the detected installation.
Install from PyPI¶
Optional extras include the base package. Choose the extra you need instead of running the plain install first.
Firefox cookie import needs no extra dependency. To import from Chrome, Brave or Chromium on macOS or Linux install the browser extra:
This installs Spotify Monitor and the optional pycookiecheat dependency.
Artwork in ntfy alerts is optional. Install the artwork extra to attach playlist and album covers to ntfy notifications:
This installs Spotify Monitor and the optional Pillow dependency. Python 3.10 and newer get the current Pillow, while Python 3.9 gets the last release that still supports it. After installing, set NTFY_IMAGES to True in the configuration file. The Docker images already include this dependency.
Spotipy is optional. Install the legacy OAuth extra only if you already have working Spotify OAuth App credentials and want to enable the optional legacy Web API metadata path. The automatic web-player backend works without this extra:
This includes Spotify Monitor and Spotipy.
Extras can be installed together:
Install the Manual Script¶
Download the script and dependency list into the same directory:
curl -fsSLO https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/spotify_monitor.py
curl -fsSLO https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/requirements.txt
You can also download spotify_monitor.py and requirements.txt in a browser or use the files from a cloned repository.
Install the core dependencies:
You can install the core dependencies directly if you downloaded only the script:
For optional legacy OAuth support install spotipy:
For optional Chrome, Brave or Chromium import on macOS or Linux install pycookiecheat:
For optional artwork in ntfy alerts install Pillow, then set NTFY_IMAGES to True in the configuration file:
On Python 3.9 install the last release that supports it instead:
On the classic Windows Command Prompt, install colorama for better coloured output:
Verify the script:
Use python spotify_monitor.py --version on Windows.
Install from Docker Hub¶
The published misiektoja/spotify-monitor image supports linux/amd64 and linux/arm64.
No separate image download is required. Its first-run command uses docker run --pull=always to pull the current image and start the setup wizard in one step, so for Docker installing and setting up are a single command:
docker run --rm --pull=always -it --init -v "${PWD}:/data:z" misiektoja/spotify-monitor:latest --setup
On a native Linux container engine, add --user "$(id -u):$(id -g)" immediately after --init. Setup & First Run shows the exact command for macOS shells, Windows PowerShell and native Linux engines then explains what the wizard asks.
Normal monitoring commands reuse the installed image and do not check for a newer release. The upgrade instructions pull explicitly when you choose to upgrade.
Normal runs make the current directory available as /data in the container. Configuration and output written there remain on the host after the temporary container stops. On a native Linux container engine, the command also passes your numeric user and group IDs so new files belong to you.
The macOS shell and Windows PowerShell examples use ${PWD}. In Windows Command Prompt use %cd% for the current directory. Native Linux examples use $PWD and pass your numeric user and group IDs.
On Windows, configure Docker Desktop or another Docker-compatible runtime to use Linux containers. Guided setup supports Firefox import from the normal %APPDATA%\Mozilla\Firefox profile root and prints shell-specific commands for PowerShell or Command Prompt. Firefox from the Microsoft Store keeps its profiles inside its own package folder, which these commands do not mount, so import that profile with a native install of the tool instead.
The :z suffix lets Docker relabel the mounted directory on hosts that use SELinux. If your Docker-compatible runtime reports that :z is invalid, remove only :z and keep the rest of the mount.
The published image includes the core dependencies but not the optional legacy-oauth or Chromium browser extras. Anonymous web-player metadata works without Spotipy. Firefox works inside a container when its cookie database is mounted read-only for the import command. Chrome, Brave and Chromium need the host password service to decrypt cookies. A container cannot use that service. See Container Operation for the complete Firefox commands. If manual extraction is needed, the hidden --set-sp-dc command is the recommended and most secure entry method.
Install with Docker Compose¶
Compose adds a reusable project file and shorter commands for later runs. Create or choose a directory for Spotify Monitor and download the Compose file there:
curl -fsSLO https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/docker-compose.yml
You can also download docker-compose.yml in a browser or use the file from a cloned repository.
On a native Linux container engine, the container does not automatically know which host user should own new files. Export your numeric user ID and group ID so configuration, logs and CSV files created by the container belong to your account instead of root:
Run these commands in the same terminal that you will use for setup and later Compose commands. A new terminal will not keep the exported values. To make them permanent for this project, put the numeric results from id -u and id -g in the Compose .env file:
The values above are only examples. Use the numbers returned on your system. The setup wizard keeps unrelated entries in this file. Docker-compatible runtimes on macOS and Windows normally handle bind-mount ownership, so users on those systems can usually skip this step. If /data is not writable, set the host user and group IDs as shown above.
Compose makes the current host directory available as /data inside the container. This is called a bind mount. The setup wizard creates spotify_monitor.conf and .env there, so the files remain on your computer when the container is replaced. From this directory your first command is the setup wizard:
On native Linux, set the UID and GID above in the same terminal before setup. Continue with Setup & First Run.
Build the Docker Image Locally¶
From a cloned repository:
docker build --pull --no-cache --tag spotify-monitor:local .
docker run --rm spotify-monitor:local --version
To use this image through Compose, comment out image: in docker-compose.yml and uncomment build: ..
Next Step¶
Continue to Setup & First Run. It shows the setup wizard command for every installation method then explains authentication and the first monitoring run.
Upgrading¶
Upgrading the package or image does not remove your configuration, .env secrets, logs or CSV files. Keep those files in the same working directory or another persistent location.
Upgrade a PyPI Installation¶
Retain any optional extras you use during the upgrade:
Upgrade a Manual Installation¶
Replace spotify_monitor.py and requirements.txt with the newest copies. You can download them in a browser, use the files from an updated clone or run:
curl -fsSLO https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/spotify_monitor.py
curl -fsSLO https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/requirements.txt
pip install --upgrade -r requirements.txt
python3 spotify_monitor.py --version
Refresh the dependencies even when requirements.txt appears unchanged because a new release may add or change a required library.
Use python spotify_monitor.py --version on Windows. If you modified the script itself, save your changes before replacing it and reapply them to the new version.
Upgrade a Docker Compose Installation¶
Stop an attached run with Ctrl+C. From the directory that contains docker-compose.yml run:
Compose replaces the service container with one based on the current latest image. The host files spotify_monitor.conf and .env remain in place with the logs and CSV files.
Upgrade a Direct Docker Installation¶
Stop the current run then pull the current image:
docker pull misiektoja/spotify-monitor:latest
docker run --rm misiektoja/spotify-monitor:latest --version
Start the tool again with the same /data mount and options you used before. If your command uses a version such as 3.0 instead of latest, replace that version yourself when you want to upgrade. Each release publishes latest plus tags in vX.Y and X.Y forms.
For example, to pin version 3.0:
Upgrade a Locally Built Docker Image¶
Rebuild from the updated repository and refresh the base image:
docker build --pull --no-cache --tag spotify-monitor:local .
docker run --rm spotify-monitor:local --version
Check Upgrade¶
After any upgrade run the doctor command for your installation:
For Docker Compose use docker compose run --rm spotify_monitor --doctor. For a direct image use the normal /data mount plus --doctor.