Requirements | browsershot | Spatie

 SPATIE

  Browsershot
==============

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Browsershot](https://spatie.be/docs/browsershot/v4)  Requirements

 Version   v4   v3

 Other versions for crawler [v4](https://spatie.be/docs/browsershot/v4) [v3](https://spatie.be/docs/browsershot/v3)

- [ Introduction ](https://spatie.be/docs/browsershot/v4/introduction)
- [ Support us ](https://spatie.be/docs/browsershot/v4/support-us)
- [ Requirements ](https://spatie.be/docs/browsershot/v4/requirements)
- [ Installation & setup ](https://spatie.be/docs/browsershot/v4/installation-setup)
- [ Upgrading ](https://spatie.be/docs/browsershot/v4/upgrading)
- [ Questions and issues ](https://spatie.be/docs/browsershot/v4/questions-issues)
- [ Changelog ](https://spatie.be/docs/browsershot/v4/changelog)
- [ About us ](https://spatie.be/docs/browsershot/v4/about-us)

Usage
-----

- [ Introduction ](https://spatie.be/docs/browsershot/v4/usage/introduction)
- [ Creating images ](https://spatie.be/docs/browsershot/v4/usage/creating-images)
- [ Creating PDFs ](https://spatie.be/docs/browsershot/v4/usage/creating-pdfs)
- [ Creating HTML ](https://spatie.be/docs/browsershot/v4/usage/creating-html)

Miscellaneous options
---------------------

- [ Adding extra headers to every request ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/adding-extra-headers-to-every-request)
- [ Adding extra headers to the navigational request ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/adding-extra-headers-to-the-navigational-request)
- [ Changing the language of the browser ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/changing-the-language-of-the-browser)
- [ Changing the value of a dropdown ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/changing-the-value-of-a-dropdown)
- [ Clicking on the page ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/clicking-on-the-page)
- [ Connection to a remote chromium/chrome instance ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/connection-to-a-remote-chrome-instance)
- [ Disable sandboxing ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/disable-sandboxing)
- [ Fixing cors issues ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/fixing-cors-options)
- [ Getting console output ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/getting-console-ouput)
- [ Getting failed requests ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/getting-failed-requests)
- [ Ignore HTTPS errors ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/ignore-https-errors)
- [ Passing environment variables to the browser ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/passing-environment-variables-to-the-browser)
- [ Performance ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/performance)
- [ Prevent unsuccessful responses ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/prevent-unsuccessful-responses)
- [ Sending POST requests ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/sending-post-requests)
- [ Setting an arbitrary option ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/setting-an-arbirary-option)
- [ Setting the CSS media type of the page ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/setting-the-css-media-type-of-the-page)
- [ Setting the timeout ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/setting-the-timeout)
- [ Setting the user agent ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/setting-the-user-agent)
- [ Specifying-a-proxy-server ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/specifying-a-proxy-server)
- [ Typing on the page ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/typing-on-the-page)
- [ Using a pipe instead of a WebSocket ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/using-a-pipe-instead-of-a-websocket)
- [ Using cookies ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/using-cookies)
- [ Using HTTP Authentication ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/using-http-authentication)
- [ Using url for html content ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/using-url-for-html-content)
- [ Writing options to a file ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/writing-options-to-a-file)
- [ Disabling redirects ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/disabling-redirects)
- [ Read redirect history ](https://spatie.be/docs/browsershot/v4/miscellaneous-options/read-redirect-history)

 Requirements
============

This package requires Node 22.0 (LTS) or higher and the Puppeteer Node library (v23.0 or higher).

### Installing puppeteer on MacOS

On MacOS you can install Puppeteer in your project via NPM:

```
npm install puppeteer
```

Or you could opt to just install it globally

```
npm install puppeteer --location=global
```

### Installing puppeteer on a Forge provisioned server

On a [Forge](https://forge.laravel.com) provisioned Ubuntu v24.04 server you can install the latest stable version of Chrome like this:

```
# Check if node and npm are installed
node -v && npm -v

# Install puppeteer
sudo npm install -g puppeteer

# Install chromium
npx puppeteer browsers install chrome

# Install dependencies
sudo apt update
sudo apt install libx11-xcb1 libxcomposite1 libasound2t64 libatk1.0-0 libatk-bridge2.0-0 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6
```

If you are using Ubuntu v22.04, replace `libasound2t64` by `libasound2`

### Custom node and npm binaries

Depending on your setup, node or npm might be not directly available to Browsershot. If you need to manually set these binary paths, you can do this by calling the `setNodeBinary` and `setNpmBinary` method.

```
Browsershot::html('Foo')
    ->setNodeBinary('/usr/local/bin/node')
    ->setNpmBinary('/usr/local/bin/npm');
```

By default, Browsershot will use `node` and `npm` to execute commands.

### Custom include path

If you don't want to manually specify binary paths, but rather modify the include path in general, you can set it using the `setIncludePath` method.

```
Browsershot::html('Foo')
    ->setIncludePath('$PATH:/usr/local/bin')
```

Setting the include path can be useful in cases where `node` and `npm` can not be found automatically.

### Custom node environment variables

If you need to set custom environment variables `node` should run with, you can use the `setNodeEnv` method.

```
Browsershot::html('Foo')
    ->setNodeEnv(['NODE_ENV' => 'production'])
```

### Custom node module path

If you want to use an alternative `node_modules` source you can set it using the `setNodeModulePath` method.

```
Browsershot::html('Foo')
  ->setNodeModulePath("/path/to/my/project/node_modules/")
```

### Custom binary path

If you want to use an alternative script source you can set it using the `setBinPath` method.

```
Browsershot::html('Foo')
  ->setBinPath("/path/to/my/project/my_script.js")
```

### Custom chrome/chromium executable path

If you want to use an alternative chrome or chromium executable from what is installed by puppeteer you can set it using the `setChromePath` method.

```
Browsershot::html('Foo')
  ->setChromePath("/path/to/my/chrome")
```

### Pass custom arguments to Chromium

If you need to pass custom arguments to Chromium, use the `addChromiumArguments` method.

The method accepts an `array` of key/value pairs, or simply values. All of these arguments will automatically be prefixed with `--`.

```
Browsershot::html('Foo')
  ->addChromiumArguments([
      'some-argument-without-a-value',
      'keyed-argument' => 'argument-value',
  ]);
```

If no key is provided, then the argument is passed through as-is.

Example arrayFlags that will be passed to Chromium`['foo']``--foo``['foo', 'bar']``--foo --bar``['foo', 'bar' => 'baz' ]``--foo --bar=baz`This method can be useful in order to pass a flag to fix font rendering issues on some Linux distributions (e.g. CentOS).

```
Browsershot::html('Foo')
  ->addChromiumArguments([
      'font-render-hinting' => 'none',
  ]);
```