Skip to content

⚙️ Virtualenv Instructions

Virtual Environment Tutorial

There are multiple ways of creating a Python virtual environment. This tutorial covers three of those:

  • The venv command.
  • The virtualenvwrapper mkvirtualenv command.
  • The uv commands: uv venv and uv sync.

venv creates virtual environments in the location where run (generally with Python projects).

mkvirtualenv creates virtual environments in one place (generally in your home directory).

uv venv creates virtual environments in the location where run (like venv, but faster).

Option 1: Using "venv"

macOS/Linux terminal (python3 -m venv ENV)

python3 -m venv sbase_env
source sbase_env/bin/activate

Windows CMD prompt (py -m venv ENV):

py -m venv sbase_env
call sbase_env\\Scripts\\activate

To exit a virtual env, type deactivate.

Option 2: Using virtualenvwrapper

macOS/Linux terminal:

python3 -m pip install virtualenvwrapper --force-reinstall
export WORKON_HOME=$HOME/.virtualenvs
source `which virtualenvwrapper.sh`

(Shortcut: Run source virtualenv_install.sh from the top-level SeleniumBase folder to perform the above steps.)

(If you add source `which virtualenvwrapper.sh` to your local bash file (~/.bash_profile on macOS, or ~/.bashrc on Linux), virtualenvwrapper commands such as mkvirtualenv will be available whenever you open a new command prompt.)

Windows CMD prompt:

py -m pip install virtualenvwrapper-win --force-reinstall --user

(Shortcut: Run win_virtualenv.bat from the top-level SeleniumBase folder to perform the above step.)

Create a virtual environment:

  • mkvirtualenv ENV.
mkvirtualenv sbase_env

(If you have multiple versions of Python installed on your machine, and you want your virtual environment to use a specific Python version, add --python=PATH_TO_PYTHON_EXE to your mkvirtualenv command with the Python executable to use.)

Leave your current virtual environment:

deactivate

Return to an existing virtual environment:

workon sbase_env

List all virtual environments:

workon

Delete a virtual environment:

rmvirtualenv sbase_env

Option 3: Using uv

uv is a fast Python package and project manager that can also create virtual environments.

Install uv (macOS/Linux terminal):

curl -LsSf https://astral.sh/uv/install.sh | sh

Install uv (Windows PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

(uv can also be installed with pip install uv, or with pip install seleniumbase[uv]. See the uv installation docs for more options.)

Create a virtual environment with uv venv:

macOS/Linux terminal:

uv venv sbase_env
source sbase_env/bin/activate

Windows CMD prompt:

uv venv sbase_env
call sbase_env\\Scripts\\activate

(If you don't provide a name, uv venv creates a virtual environment named .venv in the current directory.)

Once the virtual environment is active, install SeleniumBase with uv pip:

uv pip install seleniumbase

(Note: Virtual environments created with uv venv don't include pip by default. SeleniumBase lists pip as a dependency, so it gets installed along with SeleniumBase. For other projects, use uv pip install ... in place of pip install ..., or create the environment with uv venv --seed sbase_env to include pip from the start.)

If you want your virtual environment to use a specific Python version, add --python to your uv venv command. uv can download that Python version for you if it isn't installed yet:

uv venv --python 3.15 sbase_env

(To install a Python version without creating a virtual environment, use: uv python install 3.15.)

To exit a virtual env, type deactivate.

To delete a virtual env, remove its folder (rm -rf sbase_env on macOS/Linux, or rmdir /s /q sbase_env on Windows CMD).

Work from a local clone with uv sync:

If you've cloned the SeleniumBase repo and want to work on it locally, uv sync can create the virtual environment and install the dependencies in a single step:

git clone https://github.com/seleniumbase/SeleniumBase.git
cd SeleniumBase
uv sync

uv sync creates a .venv folder in the top-level SeleniumBase folder (if one doesn't exist yet), installs the dependencies listed in setup.py, and installs SeleniumBase itself in editable mode, so changes to your local files take effect right away. It also writes a uv.lock file that records the exact versions that were resolved.

You can activate the environment as usual:

source .venv/bin/activate

(On Windows CMD: call .venv\\Scripts\\activate)

Or skip activation and use uv run to run commands inside the environment:

uv run sbase --help
uv run pytest examples/my_first_test.py

To update the environment after pulling new changes, run uv sync again.

To use a specific Python version, add --python:

uv sync --python 3.15

Optional extras with uv sync:

SeleniumBase defines several optional extras in setup.py. Add the ones you need with --extra:

uv sync --extra mcp
uv sync --extra pillow --extra pdfminer

To install all of them at once:

uv sync --all-extras

Available extras: allure, coverage, flake8, mcp, mss, pdfminer, pillow, pip-system-certs, playwright, proxy, pyautogui, and uv.

(In an environment that was created with uv venv, the pip equivalent is uv pip install -e ".[mcp]".)

If the python and python3 versions don't match (while in a virtualenv on macOS or Linux), the following command will sync the versions:

alias python=python3

(To remove an alias, use: unalias NAME. Note that setting an alias is temporary for the current shell session. Users should add alias python=python3 to their shell profile (~/.zshrc or ~/.bashrc) if they want it to persist across terminal restarts.)

To verify the python version, use:

python --version

To see the PATH of your python (macOS/Linux), use:

which python

python-guide.org/en/latest/dev/virtualenvs has more information about Python virtual environments. For specific details about VirtualEnv and VirtualEnvWrapper, see http://virtualenv.readthedocs.org/en/latest/ and http://virtualenvwrapper.readthedocs.org/en/latest/. For uv, see docs.astral.sh/uv.