Skip to content

Fix dependency gaps that break installation on Linux #37

@danmunz

Description

@danmunz

Problem

Beta testers on Linux report that installation fails due to undocumented dependencies:

"It has all kinds of wacky dependencies that aren't specified in your README file. I tried installing it but kept running into dependency problems and finally gave up."

Root Cause Analysis

Investigation found several dependency gaps:

  1. samsungtvws is pinned to a git URL in pyproject.toml, but the package is available on PyPI as samsungtvws. The git dependency requires git to be installed, may fail behind corporate firewalls, and is slower to resolve. Fix: Change to samsungtvws>=3.0 (PyPI).

  2. Pillow system library dependencies are undocumented. Pillow requires native libraries (libjpeg-dev, zlib1g-dev, etc.) on Linux when building from source. While modern pip/uv usually pull pre-built wheels, some Linux distros or older Python versions require compilation. The README doesn't mention this.

  3. Docent.command is macOS-only but this isn't stated anywhere:

    • Uses open "$URL" (macOS-specific; Linux needs xdg-open, Windows needs start)
    • No Linux/Windows equivalent launcher is provided
    • README "Option A: Double-click" silently fails on non-macOS
  4. No requirements.txt fallback for users who don't use uv. While uv run handles everything for uv users, pip install -e . with the git dependency can fail in ways that confuse users.

Tasks

  • Switch samsungtvws from git URL to PyPI package in pyproject.toml
  • Re-lock uv.lock after the change
  • Add Linux system deps note to README Quick Start
  • Mark Option A as macOS-only in README
  • Add DOCENT_DATA_DIR env var for Docker/non-standard installs
  • Consider generating requirements.txt for pip users
  • Consider making Docent.command cross-platform (detect OS, use xdg-open on Linux)

Environment

  • Reported on: Linux (distro unspecified)
  • Python deps managed via pyproject.toml + uv
  • samsungtvws version: 3.0.4

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions