Set up a virtual environment

Syside Automator is a Python package, and the place to install it is an environment of your project’s own rather than the Python your machine came with. This tutorial explains why, then sets one up with uv or with venv and pip. If your project already has a virtual environment, or you know your way around uv or pip, go straight to Install Automator.

Why a virtual environment

A Python installed for the whole machine, whether it came with the operating system or from an installer, is shared by every script and tool on it. Installing packages into it carries three costs, each of which shows up as an error later rather than now:

  • Two projects that need different versions of the same package cannot both have it.

  • Recent Linux distributions, and Homebrew on macOS, refuse pip install outside a virtual environment altogether, with error: externally-managed-environment, because their own tools depend on that Python.

  • Nothing records what the project needs, so nobody can set it up again on a colleague’s machine or in a pipeline.

A virtual environment answers all three. It is a folder, conventionally .venv inside the project, holding a private Python plus only the packages you install into it. Deleting the folder removes everything, and the rest of the machine never notices it was there.

Choose a tool

Two tools do the job, and Syside’s install pages show a command for each:

  • uv is one program that installs Python itself, creates the environment and installs packages into it, and it records the packages in a pyproject.toml file. It works the same on every operating system, which is why this page recommends it when you have no preference.

  • venv and pip ship with Python, so nothing else needs installing, at the cost of a few operating-system differences and of activating the environment in every new terminal.

Follow one of the two sections below.

Set up with uv

  1. Install uv by following the uv installation guide for your operating system.

  2. Open a new terminal and check that uv answers:

    uv --version

    It prints the installed version.

  3. Open a terminal in the folder that will hold your scripts and create the project:

    uv init --python 3.14

    Automator needs Python 3.12 or newer, and uv downloads the version named here if the machine lacks it. Without --python, uv pins the project to whichever Python it finds first, and an older one makes uv add syside fail. The folder now holds a pyproject.toml, which records the project’s packages, a starter main.py, a README.md, a .python-version pin and a new git repository.

  4. Run Python inside the environment for the first time:

    uv run python -c "import sys; print(sys.executable)"

    uv creates the .venv folder on this first run, and the printed path ends inside it: .venv\Scripts\python.exe on Windows, .venv/bin/python on macOS and Linux.

That is the whole setup. From now on, uv add <package> installs a package into the environment and records it in pyproject.toml, and uv run <command> runs a command inside the environment from any terminal, with nothing to activate. The python and syside commands on this site are written for an activated environment, so with uv run them as uv run python ... and uv run syside .... The uv project guide covers the rest.

Set up with venv and pip

  1. Check that Python 3.12 or newer is installed. If the command is missing or reports an older version, install Python from python.org or from your Linux distribution’s packages, then open a new terminal:

    py --version

    If py is not found but python --version answers, use python in its place throughout.

    python3 --version

  2. Open a terminal in the folder that will hold your scripts and create the environment. A .venv folder appears, and nothing else on the machine changes:

    py -m venv .venv

    python3 -m venv .venv

    If this fails with ensurepip is not available, install the python3-venv package the error names and run it again. Debian and Ubuntu ship venv separately from Python.

Activate the environment

Activation makes python and pip in this terminal mean the ones inside .venv, so pip install lands there. It lasts until the window closes, so every new terminal needs activating again before any pip or python command. Editors such as Visual Studio Code find a .venv in the opened folder and activate it in their own terminals.

  1. Run the activation script:

    .venv\Scripts\activate

    .venv\Scripts\Activate.ps1

    PowerShell may block the activation with a “running scripts is disabled” error. To allow scripts for this window only, run:

    Set-ExecutionPolicy Bypass -Scope Process -Force

    Then run the activation script again.

  2. Check that the environment is active:

    where.exe python

    The first line printed should end with \.venv\Scripts\python.exe.

  1. Run the activation script:

    source .venv/bin/activate

  2. Check that the environment is active:

    which python

    The printed path should end with /.venv/bin/python.

What’s next