How to Install Vibium Behind a Proxy

To install Vibium behind a proxy, export HTTP_PROXY and HTTPS_PROXY before you install so both pip and the Chrome for Testing download route through the proxy, then run pip install vibium followed by vibium install. Vibium has two distinct network steps — pip (or npm) fetches the client and Go binary, and the binary later downloads Chrome for Testing — and both honor the standard proxy environment variables. The usual failure mode is configuring only pip: the install succeeds, but the Chrome download times out because the Go binary tried a direct connection. Setting the variables in your shell once covers every step, including Chrome's own runtime traffic when your scripts run. Add NO_PROXY so internal hosts bypass the proxy, and use an authenticated URL when your proxy requires login. With those variables in place, installing Vibium on a locked-down corporate network is the same one-command flow as anywhere else.

Which environment variables does Vibium use?

Vibium relies on the conventional proxy variables that pip, the Go binary, and Chrome all read. Set them in your shell before installing:

export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.company.com"

HTTP_PROXY and HTTPS_PROXY route outbound traffic through the proxy; NO_PROXY lists hosts that should connect directly, such as your internal sites and localhost. Setting all three in one shell means every subsequent install and run inherits them.

How do I install Vibium with the proxy set?

With the variables exported, the install is the normal flow — only now both network steps go through the proxy. Run the install and the explicit Chrome fetch:

python3 -m venv .venv
source .venv/bin/activate
pip install vibium
vibium install   # downloads Chrome for Testing via the proxy

Running vibium install explicitly is the key step behind a proxy. It forces the Chrome for Testing download to happen now, in your configured shell, instead of on the first launch() where a missing proxy would cause a confusing mid-script timeout.

How do I use an authenticated proxy?

For proxies that require a username and password, embed the credentials in the proxy URL. The same URL covers pip, the Chrome download, and runtime traffic:

export HTTP_PROXY="http://user:pass@proxy.company.com:8080"
export HTTPS_PROXY="http://user:pass@proxy.company.com:8080"
pip install vibium
vibium install

If your password contains special characters like @ or :, URL-encode them (for example @ becomes %40) so the proxy URL parses correctly. Avoid hardcoding credentials in scripts or Dockerfiles — keep them in environment variables or a secrets store.

Why does the Chrome download fail when pip succeeds?

This is the single most common proxy issue, and it comes from Vibium's two-step network model. pip install vibium pulls the Python client and the platform Go binary from PyPI; that is one connection. The binary then downloads Chrome for Testing from Google's servers on first launch; that is a separate connection made by the Go binary, not by pip. If you only configured pip's proxy (for example via pip.conf) and not the shell variables, the Chrome step tries to connect directly and stalls. Exporting HTTP_PROXY and HTTPS_PROXY in the shell fixes both at once, because the Go binary reads those same variables.

How do my scripts use the proxy at run time?

Because Chrome inherits the same environment variables, your automation routes through the proxy automatically once they are set. Verify it by checking the apparent IP:

from vibium import browser_sync as browser
 
vibe = browser.launch(headless=True)
vibe.go("https://httpbin.org/ip")
print(vibe.find("body").text())   # should show the proxy's IP
vibe.quit()

If the printed IP is the proxy's and not your machine's, traffic is flowing correctly. Set NO_PROXY for any internal targets so logging into internal apps connects directly instead of bouncing through the proxy.

What if I am still blocked?

A few targeted checks resolve most remaining proxy failures:

• Test the proxy outside Vibium first with curl -x http://proxy.company.com:8080 https://httpbin.org/ip to confirm the proxy itself works.
• Confirm the variables are exported, not just set, with env | grep -i proxy — a variable set without export will not reach child processes.
• Pre-cache Chrome on a build machine that has proxy access, then ship the cached browser in your image so locked-down runners never download. See how to run Vibium in Docker.
• Pin the Vibium version so the cached browser stays stable across rebuilds, as covered in how to pin the Chrome version.

If install still fails after the proxy is confirmed working, the cause is usually elsewhere — walk through fix: Vibium install fails.

Next steps

• Fix: Vibium install fails
• How to run Vibium in Docker
• How to install Vibium in a Python venv