Choose a browser mode

Octoparse CLI supports two browser modes for run and detect.

Mode	Browser and profile	Best for
`independent`	Chrome for Testing with a temporary profile	Clean, repeatable local runs and headless automation
`user`	System Chrome or Edge with an existing profile	Sites that depend on saved cookies or signed-in state

User mode is supported on Windows and macOS. Linux uses independent Chrome.

Browser selection priority

The CLI selects a browser in this order:

--browser flag
OCTOPARSE_BROWSER environment variable
Saved octoparse browser use setting
independent

Check available profiles

octoparse browser status --browser-id chrome --json
octoparse browser profiles --browser-id chrome --json

Install the user-browser extension

The selected browser must be fully closed during installation.

octoparse browser install \
  --browser-id chrome \
  --profile "Default" \
  --force-close \
  --json

Reopen the browser once, confirm the extension is enabled, and check status again:

octoparse browser status --browser-id chrome --profile "Default" --json

In JSON mode, follow data.nextActions or error.details.nextActions until readyForUserBrowserRun is true.

Save or override the browser mode

octoparse browser use user --browser-id chrome --profile "Default" --json
octoparse browser use status
octoparse browser use independent

Override the saved choice for one command:

octoparse run <taskId> --browser user --profile "Default"
octoparse detect <url> --browser independent --auto

User mode does not support --headless.

Environment variables

OCTOPARSE_BROWSER=user octoparse run <taskId>
OCTOPARSE_BROWSER=user OCTOPARSE_BROWSER_ID=chrome OCTOPARSE_BROWSER_PROFILE=Default octoparse run <taskId>

Troubleshooting

octoparse browser close --browser-id chrome --profile "Default" --json
octoparse browser status --browser-id chrome --profile "Default" --json
octoparse doctor --json

See Troubleshooting for Chrome downloads, Linux display requirements, and user-browser setup errors.

OVERVIEW

GET STARTED

CREATE TASKS

TASKS AND RUNS

DATA

AUTOMATION

REFERENCE

Browser selection priority

Check available profiles

Install the user-browser extension

Save or override the browser mode

Environment variables

Troubleshooting

​Browser selection priority

​Check available profiles

​Install the user-browser extension

​Save or override the browser mode

​Environment variables

​Troubleshooting

Browser selection priority

Check available profiles

Install the user-browser extension

Save or override the browser mode

Environment variables

Troubleshooting