How to Install Vibium in a Python venv

To install Vibium in a Python venv, create the environment with python3 -m venv .venv, activate it, then run pip install vibium. The Vibium Python client and its platform-specific Go binary install into the venv, fully isolated from your system Python, and a follow-up vibium install pre-downloads Chrome for Testing so the first script runs fast. A virtual environment is the recommended way to install Vibium because it avoids the two most common Python install failures at once: permission errors from system-wide installs, and version conflicts between projects. Everything lives inside the .venv folder, so you can delete and recreate it freely without touching your machine's Python. The only rule to remember is consistency — install and run in the same activated environment, or you will hit a "No module named 'vibium'" error even though the package is clearly installed. Once the venv is active, Vibium behaves exactly as it does anywhere else.

How do I create and activate the venv?

Create the environment in your project folder, then activate it so pip and python point at the isolated copy. The activation command differs by platform:

mkdir my-vibium-bot
cd my-vibium-bot
python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate

After activation your shell prompt shows (.venv), confirming the environment is active. From here, pip installs into .venv, not your system Python — which is exactly what keeps the install clean.

How do I install Vibium into the venv?

With the venv active, upgrade pip and install Vibium. Upgrading pip first avoids resolver and wheel errors on older versions:

pip install --upgrade pip
pip install vibium
vibium install        # pre-download Chrome for Testing

That single pip install pulls the Vibium client plus the matching Go binary into the venv. Running vibium install afterward fetches Chrome for Testing now, so your first launch() does not pay the one-time download cost.

How do I confirm the install worked?

Verify the package is in the active environment, then launch a browser in a few lines. Check that pip can see it:

pip show vibium

If pip show reports the version and location inside .venv, you are set. Confirm Vibium actually runs:

from vibium import browser_sync as browser
 
vibe = browser.launch()
vibe.go("https://example.com")
print(vibe.find("h1").text())
vibe.quit()

A browser opening and the heading printing means the venv install is healthy. For the next step, follow your first Vibium script in Python.

Why does "No module named 'vibium'" happen in a venv?

This error almost always means your script and your install are in different environments. You installed Vibium into .venv, but you ran the script with a different Python — often because the venv was not active, or your editor is configured to use the system interpreter. The fix is to make the running environment match the install environment:

source .venv/bin/activate
pip show vibium          # confirm it is here
python my_script.py      # run from the same activated shell

If pip show finds Vibium but the import still fails when you run from your IDE, point the IDE's Python interpreter at .venv/bin/python. For more install-time errors and their fixes, see fix: Vibium install fails.

How do I manage the venv day to day?

A venv is disposable, which is its biggest advantage. A few practical habits:

• Deactivate with deactivate when you switch projects, so commands do not run in the wrong environment.
• Pin dependencies with pip freeze > requirements.txt so teammates and CI install the exact same versions. Pin Vibium itself per how to pin the Chrome version.
• Recreate freely — delete .venv and rerun the create-and-install steps if anything gets tangled. Nothing outside the folder is affected.
• Exclude it from git by adding .venv/ to .gitignore; commit requirements.txt instead.

Does the venv approach work in CI and containers?

Yes, and the same isolation benefits apply. In Docker you often skip the venv because the container is already isolated, while in GitHub Actions a venv (or setup-python) keeps the job's dependencies clean. The install commands are identical in every case — create or set up Python, then pip install vibium and vibium install. See how to use Vibium in GitHub Actions for the CI flow and how to run Vibium in Docker for the container equivalent. To understand what Vibium installs and why there is no separate driver, read what is Vibium?.

Next steps

• Your first Vibium script in Python
• Fix: Vibium install fails
• How to use Vibium in GitHub Actions