Back to iOpenPod

Install Help and Troubleshooting

Pick the install path that matches your setup. Use the fixes below only when something goes wrong.

Choose an install Find a fix

Start Here

Most users only need one of these three paths.

Best

Use uv

Best if you can copy terminal commands. uv keeps iOpenPod isolated and can manage Python for you.

uv tool install iopenpod
iopenpod
uv steps

Use pipx

Best if Python 3.11 or newer is already installed. pipx keeps app installs separate.

pipx install iopenpod
iopenpod
pipx steps
No Python

Use a native build

Best if you want a downloaded app. Native builds may show security prompts because they are not fully signed yet.

Native steps

Already installed iOpenPod more than one way? Use the cleanup steps before reinstalling.

Native Apps

Download native files from the official GitHub release page, then open the dropdown for your platform.

Latest release
Windows native app
  1. Download iOpenPod-Windows.zip.
  2. Right-click the zip and choose Extract All.
  3. Open the extracted folder.
  4. Double-click iOpenPod.exe.

If SmartScreen appears, check that the file came from the official iOpenPod GitHub release.

Then choose More info, then Run anyway.

macOS native app and security prompt
  1. Download iOpenPod-macOS.zip.
  2. Open the zip.
  3. Move iOpenPod.app to Applications if you want it installed there.
  4. Open iOpenPod.app.

The macOS app is not notarized yet. Gatekeeper may block the first launch.

Only continue if the file came from the official GitHub release.

Allow it in System Settings

  1. Open iOpenPod.app from Finder.
  2. When macOS blocks it, choose Done.
  3. Open System Settings.
  4. Go to Privacy & Security.
  5. Choose Open Anyway next to the iOpenPod message.
  6. Confirm with Touch ID or an administrator password.
Finder window showing iOpenPod.app selected before first launch
1. Open iOpenPod.app from Finder.
macOS warning dialog saying iOpenPod.app was not opened and showing Done
2. Choose Done.
Privacy and Security settings showing iOpenPod was blocked and an Open Anyway button
3. Choose Open Anyway in Privacy & Security.
macOS confirmation dialog asking whether to open iOpenPod.app and showing Open Anyway
4. Confirm with Open Anyway.
macOS authentication dialog asking for Touch ID or administrator password
5. Use Touch ID or enter an admin password.
Linux AppImage
  1. Download iOpenPod-Linux-x86_64.AppImage.
  2. Open a terminal in the download folder.
  3. Run the commands below.
chmod a+x ./iOpenPod-Linux-x86_64.AppImage
./iOpenPod-Linux-x86_64.AppImage

You can also mark the file executable in your file manager, then double-click it.

Linux tarball or Flatpak

Tarball

tar -xzf iOpenPod-Linux.tar.gz
cd iOpenPod
./iOpenPod

Flatpak bundle

flatpak install --user ./iOpenPod-Linux.flatpak
flatpak run io.github.therealsavi.iOpenPod

Flatpak is only available when the release includes iOpenPod-Linux.flatpak.

uv and pipx Installs

Use these if you prefer an install that updates from PyPI.

Best

Install with uv

If uv is not installed, follow the official uv install guide. Then reopen your terminal.

Official uv installation instructions

Install and run
uv tool install iopenpod
iopenpod
Update or remove
uv tool upgrade iopenpod
uv tool uninstall iopenpod

Install with pipx

If pipx is not installed, follow the official pipx guide. Then reopen your terminal.

Official pipx installation instructions

Install and run
pipx install iopenpod
iopenpod
Update or remove
pipx upgrade iopenpod
pipx uninstall iopenpod

Helper Tools

iOpenPod can open without these, but full sync needs them.

FFmpeg and ffprobe

Needed for media checks and audio/video conversion.

ffmpeg -version
ffprobe -version

Chromaprint fpcalc

Needed for acoustic fingerprints during matching.

fpcalc -version
Common helper tool install commands
PlatformFFmpegChromaprint / fpcalc
Windows Use the FFmpeg download page, WinGet, Scoop, or Chocolatey. Download chromaprint-fpcalc from AcoustID Chromaprint.
macOS brew install ffmpeg brew install chromaprint
Ubuntu / Debian sudo apt install ffmpeg sudo apt install libchromaprint-tools
Fedora / RPM sudo dnf install ffmpeg sudo dnf install chromaprint-tools
Arch Linux sudo pacman -S ffmpeg sudo pacman -S chromaprint
Linux Qt desktop libraries

Install these if Linux reports an xcb error or crashes when pressing Ctrl, Alt, or Shift.

Debian / Ubuntu
sudo apt install libxcb-cursor0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0 libxcb-xkb1 libxkbcommon0 libxkbcommon-x11-0
Fedora / RPM-based Linux
sudo dnf install libxcb xcb-util-cursor xcb-util-wm xcb-util-image xcb-util-keysyms xcb-util-renderutil libxkbcommon libxkbcommon-x11
Arch Linux
sudo pacman -S libxcb xcb-util-cursor xcb-util-wm xcb-util-image xcb-util-keysyms xcb-util-renderutil libxkbcommon libxkbcommon-x11

If names differ, search your distro for xcb-xkb, xkbcommon, and xkbcommon-x11.

Troubleshooting

Open the item that matches the problem you see.

iopenpod is not recognized

Your terminal cannot find the command yet.

# uv installs
uv tool update-shell

# pipx installs
pipx ensurepath

Close and reopen the terminal. On Windows, sign out and back in if PATH still has not updated.

pipx install iopenpod says Python is too old

iOpenPod requires Python 3.11 or newer.

pipx install --python python3.11 iopenpod

On Windows, list installed Python versions with:

py -0p
uv tool install iopenpod cannot download Python

Managed computers may block downloads, proxies, or TLS inspection.

Try another network, install Python 3.11 or newer yourself, or use a native build.

Windows says the app is unsafe

Unsigned open-source apps can trigger SmartScreen.

Only continue if the file came from the official iOpenPod GitHub release.

Choose More info, then Run anyway.

macOS says the developer cannot be verified

Open System Settings, then go to Privacy & Security.

Choose Open Anyway next to the iOpenPod message.

If Open Anyway does not appear, Control-click iOpenPod.app, choose Open, then confirm.

Linux says the Qt xcb platform plugin could not load

A Qt desktop library is missing. On Debian or Ubuntu, start with:

sudo apt install libxcb-cursor0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0 libxcb-xkb1 libxkbcommon0 libxkbcommon-x11-0

On a Wayland-only desktop, you can also try:

QT_QPA_PLATFORM=wayland iopenpod
Linux build crashes when pressing Ctrl, Alt, or Shift

This points to Qt's XKeyboard libraries.

Install the Linux Qt libraries above, especially libxcb-xkb1, libxkbcommon0, and libxkbcommon-x11-0.

If you use a native Linux build, download a newer iOpenPod release after those libraries were bundled.

Linux AppImage reports a FUSE error 
# Ubuntu / Debian
sudo apt install libfuse2

# Ubuntu 24.04 and newer may use this name
sudo apt install libfuse2t64

# Arch Linux
sudo pacman -S fuse2

If FUSE still fails, use the tarball, Flatpak bundle, or uv install.

Linux says the iPod is read-only or permission denied

Do not sync until a small write test works.

Find your iPod path. It often looks like /run/media/YOURNAME/IPOD or /media/YOURNAME/IPOD.

Check the mount

findmnt -T "/path/to/iPod"
lsblk -f

In findmnt, ro means read-only. rw means read-write.

Safe write test

touch "/path/to/iPod/.iopenpod-write-test"
rm "/path/to/iPod/.iopenpod-write-test"

If both commands work, iOpenPod should be able to write.

If it mounted read-only

sudo mount -o remount,rw "/path/to/iPod"

Run the write test again after remounting.

If FAT32 needs repair

Replace /dev/sdXN with the iPod partition. Using the wrong disk can damage data.

Do not run fsck while the iPod is mounted.

sudo umount "/path/to/iPod"
sudo fsck.vfat -a /dev/sdXN

Reconnect the iPod, then run the write test again.

If it is Mac-formatted

If lsblk -f shows hfsplus, Linux write support is limited.

Use macOS, or back up and restore the iPod as Windows/FAT32 before using it mainly on Linux.

If root owns the mount

Unmount, unplug, and reconnect from your desktop file manager.

Advanced manual mount:

sudo umount "/path/to/iPod"
sudo mkdir -p /mnt/ipod
sudo mount -o rw,uid=$(id -u),gid=$(id -g),umask=022 /dev/sdXN /mnt/ipod
iOpenPod opens but does not find my iPod
  • Make sure the iPod appears in Finder, File Explorer, or your Linux file manager.
  • Try another USB cable or port.
  • Close iTunes, Music, Finder sync windows, or other iPod tools.
  • On Linux, make sure the safe write test succeeds.
FFmpeg, ffprobe, or fpcalc is missing

Install the missing helper tool, restart iOpenPod, then check:

ffmpeg -version
ffprobe -version
fpcalc -version
I installed iOpenPod more than one way

Pick one install method and remove the others.

uv tool uninstall iopenpod
pipx uninstall iopenpod
python -m pip uninstall iopenpod

Then reinstall with one method, preferably uv or pipx.

Bug Report

If you encounter a bug, please submit a report!

  • Please include iopenpod.log. In iOpenPod, open Settings > Storage, then click Open next to Log Location.
Open a GitHub issue