Prepare your Python Virtual Environment

To manage Python packages for your Viam application, it is recommended that you use a virtual environment, or venv. By using a venv, you can install Python packages like Viam’s client SDK within a virtual environment, avoiding conflicts with other projects or your system.

Follow this guide to set up a fresh virtual environment on your working computer and install the Python SDK as a requirement for your Viam client application.

Install virtualenv

1. Install pip. To check if you have pip installed, run the following command:

   pip3 --version
   

   The expected output is the pip version number.

2. Install virtualenv using pip:

   python3 -m pip install --user virtualenv
   

Set up your project

First, create a directory for your project. For example, name your directory viam-python:

mkdir viam-python
cd viam-python

Create and activate a virtual environment

In the project directory, create and activate a virtual environment for Python to run in.

python3 -m venv .venv
source .venv/bin/activate

Now, .venv prepends the commands in your terminal window to indicate the Python packages being used are from this particular environment. You can exit this environment by running deactivate.

Install Viam

Inside the activated .venv Python environment, you can now install the Viam Python SDK:

pip3 install viam-sdk

This installs the Viam Python SDK and all required general dependencies.

If you intend to use the ML (machine learning) model service, install the Python SDK using the mlmodel extra:

pip3 install 'viam-sdk[mlmodel]'

This installs the Viam Python SDK and all required dependencies, including for the ML model service.

You can also run this command on an existing Python SDK install to add support for the ML model service.

If you need to install your own requirements, also install them in this virtual environment. To make your required packages easier to install in the future, you can also create a requirements.txt file with a list of all the packages you need and then install the requirements for your client application by running pip3 install -r requirements.txt.

Set up your IDE

If you would like to be able to use the environment you created with your IDE, point your IDE to use the Python interpreter of your new environment, rather than the default interpreter, likely the global Python interpreter.

The following steps are for VS Code. If you’re not using VS Code, please read your IDE’s documentation on selecting Python interpreters.

1. Open the viam-python directory in VS Code
2. Open the Command Palette (using ⇧⌘P or through the menus View -> Command Palette)
3. Select the command Python: Select Interpreter. There, you should see all the interpreters available to you. You’re looking for the on you just made: .venv. It will look something like: Python 3.XX.X ('.venv': venv) ./.venv/bin/python. If you don’t see it, click the Refresh icon on the top right of the Command Palette. Select the .venv interpreter.

Your IDE will now recognize all packages installed in this environment.

Start building

You are now ready to start using Viam’s Python SDK!