Playwright CLI Session Management: Multiple Browser Sessions, Isolation, Persistence, and Cleanup

Wed, 15 Apr 2026 08:15:12 +0800

If you use Playwright CLI for automation, you will quickly run into a practical question: can you open multiple browser sessions at the same time without them interfering with each other? The answer is yes, and Playwright CLI already makes this mechanism quite straightforward.

Following the official session-management reference, this article focuses on its most practical pieces: named sessions, session isolation, persistent profiles, concurrent patterns, and common cleanup commands. The command lines and command block explanations are preserved from the reference content.

01 Named Browser Sessions

The official recommendation is to use the -s parameter to isolate different browser contexts:

# Browser 1: Authentication flow
playwright-cli -s=auth open https://app.example.com/login

# Browser 2: Public browsing (separate cookies, storage)
playwright-cli -s=public open https://example.com

# Commands are isolated by browser session
playwright-cli -s=auth fill e1 "user@example.com"
playwright-cli -s=public snapshot

The key point here is that different session names map to different browser contexts. You can use auth for the sign-in flow and public for anonymous browsing, and they will not share cookies or local state.

02 What Does Browser Session Isolation Separate?

Each browser session maintains the following items independently:

Cookies
LocalStorage / SessionStorage
IndexedDB
Cache
Browsing history
Open tabs

That means if you sign in to a site in the auth session, it will not automatically affect the public session. This is especially important for multi-account testing, login-state verification, and anonymous-vs-authenticated comparisons.

The official documentation groups the most commonly used session-management commands together:

# List all browser sessions
playwright-cli list

# Stop a browser session (close the browser)
playwright-cli close                 # stop the default browser
playwright-cli -s=mysession close   # stop a named browser

# Stop all browser sessions
playwright-cli close-all

# Forcefully kill all daemon processes (for stale/zombie processes)
playwright-cli kill-all

# Delete browser session user data (profile directory)
playwright-cli delete-data              # delete default browser data
playwright-cli -s=mysession delete-data # delete named browser data

You can think of them as three kinds of operations:

list: see which sessions currently exist
close / close-all / kill-all: stop sessions or clean up stuck browser processes
delete-data: remove the user data directory for a specific session

If you just want to close a browser, close is usually the first choice. If leftover or zombie processes have already appeared, kill-all is the better fit.

04 Set a Default Session with an Environment Variable

If you do not want to repeat -s=mysession on every command, the official docs also provide an environment-variable approach:

1
2

export PLAYWRIGHT_CLI_SESSION="mysession"
playwright-cli open example.com  # Uses "mysession" automatically

After that, when you do not explicitly specify -s, the command will use mysession as the default browser session.

05 Common Pattern: Concurrent Scraping

The reference gives a very typical concurrent-scraping example:

#!/bin/bash
# Scrape multiple sites concurrently

# Start all browsers
playwright-cli -s=site1 open https://site1.com &
playwright-cli -s=site2 open https://site2.com &
playwright-cli -s=site3 open https://site3.com &
wait

# Take snapshots from each
playwright-cli -s=site1 snapshot
playwright-cli -s=site2 snapshot
playwright-cli -s=site3 snapshot

# Cleanup
playwright-cli close-all

This pattern works well when you want to open multiple sites at once, capture each page state, and then clean everything up together. Because each site runs in an independent session, they do not contaminate each other’s local state.

06 Common Pattern: A/B Test Sessions

Another common scenario is comparing different experiment variants at the same time:

# Test different user experiences
playwright-cli -s=variant-a open "https://app.com?variant=a"
playwright-cli -s=variant-b open "https://app.com?variant=b"

# Compare
playwright-cli -s=variant-a screenshot
playwright-cli -s=variant-b screenshot

This style is great for A/B page comparisons because the two variants run in separate sessions, making screenshots and state checks easier to manage independently.

07 Persisting Browser Profiles

The official documentation specifically points out that browser profiles are stored only in memory by default.

If you want to persist a browser profile to disk, add --persistent when running open:

# Use persistent profile (auto-generated location)
playwright-cli open https://example.com --persistent

# Use persistent profile with custom directory
playwright-cli open https://example.com --profile=/path/to/profile

This capability is useful when you need to reuse login state, local cache, or an extension-debugging environment over the long term. When repeatedly debugging the same site, a persistent profile is often much more efficient than starting from scratch every time.

08 The Default Browser Session

If -s is not explicitly provided, the command uses the default browser session:

# These use the same default browser session
playwright-cli open https://example.com
playwright-cli snapshot
playwright-cli close  # Stops default browser

In other words, commands without -s are executed continuously within the same default session.

In addition to the session name, the official docs also show several common startup configuration patterns:

# Open with config file
playwright-cli open https://example.com --config=.playwright/my-cli.json

# Open with specific browser
playwright-cli open https://example.com --browser=firefox

# Open in headed mode
playwright-cli open https://example.com --headed

# Open with persistent profile
playwright-cli open https://example.com --persistent

These parameters can be combined with session management. For example, you can make one named session always run in firefox, or make a specific session always launch in headed mode for easier manual inspection.

10 Best Practices from the Official Docs

The reference lists three practical best practices.

1. Use Meaningful Session Names

# GOOD: Clear purpose
playwright-cli -s=github-auth open https://github.com
playwright-cli -s=docs-scrape open https://docs.example.com

# AVOID: Generic names
playwright-cli -s=s1 open https://github.com

Session names should ideally communicate their purpose directly. Names like github-auth and docs-scrape make later script maintenance much clearer.

2. Clean Up Promptly After Use

# Stop browsers when done
playwright-cli -s=auth close
playwright-cli -s=scrape close

# Or stop all at once
playwright-cli close-all

# If browsers become unresponsive or zombie processes remain
playwright-cli kill-all

If you do not close the browser after a task finishes, the session and background processes will remain. That may not seem serious in the short term, but once tasks pile up, the environment can become messy very quickly.

3. Remove Stale Browser Data

1
2

# Remove old browser data to free disk space
playwright-cli -s=oldsession delete-data

When some old sessions are no longer needed, deleting their data directories saves disk space and also helps avoid accidentally reusing outdated state later.

11 Quick Summary

If you only want the essentials, remember these points:

-s=<name> creates and uses an independent browser session
Different sessions isolate cookies, different kinds of storage, cache, history, and tabs
close-all is useful for unified shutdown, while kill-all is useful for cleaning up abnormal leftover processes
--persistent writes the profile to disk and is useful for long-term state reuse
Session names should be meaningful, and old data should be cleaned up regularly

If your workflow already includes reused login states, parallel multi-account work, A/B comparisons, or batch scraping, then session management is basically one of the most worthwhile pieces of Playwright CLI to learn first.

References

Playwright CLI session-management reference: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/session-management.md
Playwright CLI project homepage: https://github.com/microsoft/playwright-cli

Session Management on KnightLi Blog