Skip to content

docs(playwright): warn against playwright install-deps without root#2737

Draft
DaveHanns wants to merge 1 commit into
apify:masterfrom
DaveHanns:docs-playwright-install-deps-warning
Draft

docs(playwright): warn against playwright install-deps without root#2737
DaveHanns wants to merge 1 commit into
apify:masterfrom
DaveHanns:docs-playwright-install-deps-warning

Conversation

@DaveHanns

Copy link
Copy Markdown
Contributor

Summary

Add a note in the Dockerfile reference explaining that users developing a Playwright Actor locally should not run npx playwright install-deps. That command requires sudo, and in unprivileged environments (agent sandboxes, restricted shells, some CI runners) it fails with a cryptic error and blocks the user from making progress.

The apify/actor-node-playwright-* base images already include every system library Playwright needs, so the workaround is just: rely on the base image via apify run, or push to Apify and run remotely.

Rationale

When a user new to Playwright follows the Playwright docs verbatim and runs the recommended local setup command:

$ npx playwright install-deps
BEWARE: your OS is not officially supported by Playwright; installing dependencies for Ubuntu Jammy (22.04) LTS as a fallback.
Switching to root user to install dependencies...
su: must be suid to work properly
Failed to install browser dependencies

...they hit a dead end. Nothing in the current Dockerfile docs tells them that this step is redundant when using an Apify base image. Adding one small note under the "Node.js base images" section prevents the whole class of "Playwright won't install locally" support questions.

Change

sources/platform/actors/development/actor_definition/docker.md — add a :::note admonition immediately below the Node.js base images table, covering:

  • Base images already ship libnss3, libatk1.0-0, etc.
  • playwright install-deps requires root and will fail as shown above in unprivileged environments.
  • Preferred paths: apify run (uses the base image) or apify push + run remotely.
  • npx playwright install (browser binaries only, user-owned dir) is still fine.

Test plan

  • Docs page renders the new admonition below the Node.js base images table.
  • Links (apify run, apify push) resolve to the CLI reference.
  • No typos flagged by typos.toml.

Surfaced during an evaluation of Apify surfaces for agent-driven Actor development.

The `actor-node-playwright-*` Docker images already ship every system
library Playwright needs, so users setting up a local Actor project
should not run `npx playwright install-deps`. That command shells out
to `sudo`/`su` to install Debian packages, and in unprivileged
environments (agent sandboxes, restricted shells, some CI runners) it
fails with a cryptic `su: must be suid to work properly. Failed to
install browser dependencies.` message that offers no actionable next
step.

Add a note under "Node.js base images" in the Dockerfile reference
that:

- explains why `install-deps` is not needed when using the base image,
- recommends `apify run` (which uses the image) or `apify push`
  followed by a remote run instead, and
- calls out that `npx playwright install` (browser download only,
  writes to the user's cache dir) is still safe to run locally.

Surfaced during an evaluation of Apify surfaces for agent-driven Actor development.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@DaveHanns DaveHanns marked this pull request as draft July 5, 2026 11:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants