The Playwright --with-deps Flag: When It Helps and When It Breaks Production
When deploying PixelPerfect Screenshot API to Render.com, I followed what seemed like obvious advice: on a Linux server, use --with-deps when installing Playwright. Every tutorial said so. Every Stack Overflow answer confirmed it. So I added it to the build command and pushed.
The build failed immediately.
The fix, once I found it, was to remove the flag entirely — the exact thing everyone said was required. The moment I did, the build succeeded, Chromium launched without errors, and screenshots worked in production on the first request.
This article explains what actually happened, why managed platforms behave differently than bare Linux servers, and how to figure out which approach your specific hosting environment needs.
What the Failure Looked Like
Here's the exact output from the Render.com build logs with --with-deps:
pip install -r requirements.txt &&
python -m playwright install --with-deps chromium
Feb 6 12:04:02 AM
Feb 6 12:04:02 AM Switching to root user to install dependencies...
Feb 6 12:04:03 AM Password: su: Authentication failure
Feb 6 12:04:03 AM Failed to install browsers
Feb 6 12:04:03 AM Error: Build failed
The flag was trying to run sudo apt-get install to add system packages. Render.com blocks root access during builds for security reasons. The authentication failure killed the entire deployment before a single line of application code ran.
What --with-deps actually does: It doesn't just install the Chromium binary — it also runs sudo apt-get install to add system-level libraries that Chromium depends on. On any platform that restricts root access, this fails hard, and it fails before Playwright even attempts to download the browser.
What the Fix Looked Like
After removing --with-deps:
pip install -r requirements.txt &&
python -m playwright install chromium
Feb 6 12:12:57 AM
Feb 6 12:12:57 AM Playwright browsers installed successfully
Feb 6 12:12:58 AM ✅ Database tables created successfully
Feb 6 12:12:59 AM ==> Your service is live 🎉
Same command, just without the flag. Clean build, service live, Chromium launching correctly on every screenshot request.
Why it worked without the flag: Render.com's Ubuntu environment already includes all the system libraries Chromium needs. The flag was trying to install packages that were already there — and failing because it lacked permission to do so. Removing the flag let Playwright do the only thing it actually needed to do: download the Chromium binary itself.
- Attempted sudo apt-get install
- Render blocked authentication
- Build failed at line 1
- Service never started
- Zero screenshots served
- Downloaded Chromium binary only
- Used existing system libraries
- No root access needed
- Build completed in seconds
- Service live and taking screenshots
The lesson isn't that --with-deps is wrong — it's that it's designed for bare Linux servers, not managed hosting platforms that pre-install the dependencies it's trying to add.
Understanding What the Flag Does (and Why It Exists)
Playwright's Chromium binary depends on a long list of Linux system libraries — things like libnss3 for SSL/TLS, libatk1.0-0 for accessibility support, libgbm1 for GPU buffer management, font libraries, and more. On a minimal Linux server that's been freshly provisioned, none of these are installed by default.
The --with-deps flag automates installing all of them via sudo apt-get. On a bare Ubuntu 22.04 VPS where you have root access, this is genuinely useful. Managed platforms like Render.com solve the same problem differently: they pre-install those libraries in their base image. The flag tries to install what's already there, can't get root access, and crashes.
When You Need --with-deps
Bare Linux servers (EC2, DigitalOcean, Linode)
python -m playwright install --with-deps chromium
Docker containers with slim base images
RUN pip install playwright
RUN python -m playwright install --with-deps chromium
GitHub Actions and most CI/CD runners
run: |
pip install playwright
python -m playwright install --with-deps chromium
When You Don't Need --with-deps
Render.com (confirmed from PixelPerfect)
pip install -r requirements.txt && python -m playwright install chromium
Railway.app
Railway's Nixpacks builder handles system dependencies automatically. Plain install works.
Heroku
Heroku has a dedicated Playwright buildpack that manages everything. Follow their specific integration guide rather than using the flag.
The official Playwright Docker image
# Browsers already installed — just install your app dependencies
RUN pip install -r requirements.txt
| Platform | Use --with-deps? | Why |
|---|---|---|
| Render.com | ✗ NO | Dependencies pre-installed; root access blocked |
| Railway.app | ✗ NO | Nixpacks handles dependencies automatically |
| Heroku | ✗ NO | Use the official Playwright buildpack |
| Playwright Docker image | ✗ NO | Everything already in the image |
| AWS EC2 (bare) | ✓ YES | Minimal OS needs system packages |
| DigitalOcean Droplet | ✓ YES | Bare Ubuntu lacks Chromium dependencies |
| Docker slim base image | ✓ YES | Slim images exclude system libraries |
| GitHub Actions (standard) | ✓ YES | Runners start minimal |
Default approach: Try without --with-deps first on any managed platform. If Chromium fails to launch at runtime with a missing library error, add it. Failing with an authentication error during build means you definitely don't need it.
The Working PixelPerfect Configuration
requirements.txt comment (saves future confusion)
uvicorn[standard]>=0.24.0
playwright>=1.40.0
Pillow>=10.0.0
# Deployment note for Render.com:
# Do NOT use --with-deps in the build command.
# Render's environment pre-installs all Chromium system dependencies.
# --with-deps attempts sudo apt-get which Render blocks, breaking the build.
# Build command: pip install -r requirements.txt && python -m playwright install chromium
#
# For bare Linux (EC2, DigitalOcean): --with-deps IS needed.
Render build command
Startup command
A Quick Troubleshooting Guide
Build fails with "Authentication failure" or "sudo: command not found" — You used --with-deps on a platform that blocks root access. Remove the flag.
Build succeeds but Chromium crashes at runtime with "error while loading shared libraries" — The system is missing a library Chromium needs. You're probably on a bare server or slim Docker image and do need --with-deps.
Build succeeds, Chromium launches, but nothing renders — Likely a missing font package or sandbox issue. Try adding --no-sandbox to your Playwright launch options as a first diagnostic step.
Comments
Post a Comment