docs(sdk): install openhands-sdk and openhands-tools as a matched set#512
Conversation
The PyPI install instructions ran four separate pip commands without version alignment. Because openhands-tools depends on openhands-sdk without a version constraint and imports its internals directly, this can produce a mismatched pair (e.g. a newer openhands-tools against an older, not-upgraded openhands-sdk), which fails at import with ModuleNotFoundError: No module named 'openhands.sdk.utils.path'. Install the packages together in a single pip command, use -U so an existing copy is upgraded, and add a warning that the two packages must stay on the same version.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
🟢 Good taste - Excellent pragmatic documentation fix.
This change solves a real user problem (version mismatches causing ModuleNotFoundError) by consolidating installation commands and adding clear warnings. The -U flag ensures existing packages are upgraded, and the detailed warning explains why version alignment matters.
[RISK ASSESSMENT]
- [Overall PR]
⚠️ Risk Assessment: 🟢 LOW
Documentation-only change that improves user experience and prevents installation issues. No code modifications, no breaking changes.
VERDICT:
✅ Worth merging: Prevents silent version mismatches with clear, actionable guidance.
KEY INSIGHT:
Combining installation commands with -U eliminates the most common source of version mismatch errors while maintaining simplicity.
Was this automated review useful? React with 👍 or 👎 to this review to help us measure review quality.
Workflow run: https://github.com/OpenHands/docs/actions/runs/26167116322
4 participants
What
Updates the SDK Getting Started page (
sdk/getting-started.mdx, Step 2 → Option 1: Install via PyPI) so the core packages are installed as a matched set, and adds a warning that they must stay on the same version.Why
The current instructions run four separate
pip installcommands with no version alignment:openhands-toolsdepends onopenhands-sdkwithout a version constraint and imports its internals directly (it pulls in ~29 distinctopenhands.sdk.*modules, including internal paths likeconversation.impl.local_conversation,event.base,llm.llm, andutils.path). Becausepip install <pkg>does not upgrade an already-installed copy, the separate-command pattern can leave a neweropenhands-toolsagainst an olderopenhands-sdk.That mismatch fails at import — e.g.
openhands-tools≥ 1.20.0 importsopenhands.sdk.utils.path, a module absent from older SDK releases (e.g. 1.17.0):Reported in OpenHands/software-agent-sdk#3300.
Closes OpenHands/software-agent-sdk#3300.
Change
openhands-sdkandopenhands-toolsin a singlepipcommand, with-Uso a stale copy is upgraded.<Warning>explaining the two packages are a matched set that must share the same version, with the exact symptom of a mismatch and a pinned-install example.This is a docs-only change. A complementary code fix (pinning the dependency in
openhands-tools) can follow separately.