Create a Virtual Environment

It is strongly recommended to install the package inside a dedicated virtual environment rather than into your system-wide Python installation. This keeps the package and its dependencies isolated from other projects and avoids version conflicts.

This step is shared by both installation methods — do this first, then continue to either Install with pip or Install with Poetry.

1. Choose a location for the environment

Create the virtual environment inside your project folder, typically named .venv or venv. From your project's root directory, run the appropriate command below.

2. Create the environment

Windows (PowerShell):

python -m venv .venv

Windows (cmd.exe):

python -m venv .venv

macOS / Linux (bash/zsh):

python3 -m venv .venv

This creates a .venv folder in your project directory containing a self-contained copy of the Python interpreter, pip, and the venv standard library module. No packages are installed yet — the environment is empty except for the base tooling.

If python is not recognized, verify Python 3.12+ is installed and added to your PATH. You can check your installed version with python --version (or python3 --version on macOS/Linux).

3. Activate the environment

You must activate the environment in every new terminal session before installing or using the package.

Windows (PowerShell):

.venv\Scripts\Activate.ps1

If activation fails with a message about execution policies, PowerShell's script execution is restricted. Allow local scripts for your user account by running:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Then re-run the activation command.

Windows (cmd.exe):

.venv\Scripts\activate.bat

macOS / Linux (bash/zsh):

source .venv/bin/activate

Once activated, your shell prompt is prefixed with (.venv), indicating that the environment is active. Any pip install or python command now runs inside the isolated environment rather than affecting your system Python.

4. Deactivate when finished

When you are done working, you can leave the virtual environment with:

deactivate

This works the same way on Windows, macOS, and Linux. Deactivating returns your shell to using the system Python. You do not need to deactivate before closing the terminal — the environment is only active for the current session.

Next steps

With the virtual environment created and activated, continue with your chosen installation method:

• Install with pip
• Install with Poetry