> For the complete documentation index, see [llms.txt](https://docs.envector.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.envector.io/1.4.x/get-started/installation/client-sdk.md).

# Client SDK

This guide provides instructions for installing the enVector SDK across different environments. Whether you're working on a local machine or in the cloud, we've got you covered.

## Prerequisites

* Python version requirements: Python `3.9 ≤ version ≤ 3.13`
* pip (Python package installer)
* virtualenv (recommended for isolated environments)

> ⚠️ **Note**: Intel-based macOS devices are not supported. If you have an Intel Mac, run a Linux environment inside a Docker container (e.g., Ubuntu via Docker Desktop) and follow the [Linux installation steps](#-linux-x86_64--arm64) there.

## Installation by Platform

### 🐧 Linux (x86\_64 & arm64)

This guide is for users on common Linux distributions with either x86\_64 (AMD/Intel) or arm64 architectures.

**1. Install System Dependencies (Python `3.9 ≤ version ≤ 3.13`)**

Linux distributions have different package managers depending on the distribution. The most reliable way to manage Python versions without interfering with system packages is to use pyenv.

* If you don't have Python `3.9 ≤ version ≤ 3.13`, we strongly recommend installing it with pyenv. This tool lets you install specific Python versions in your user directory.

a. Install pyenv build dependencies. Before installing pyenv, you need packages to build Python from source.

* On Ubuntu/Debian:

  ```bash
  sudo apt-get update && sudo apt-get install make build-essential libssl-dev zlib1g-dev \
      libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
      libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
  ```
* On Fedora/CentOS/RHEL:

  ```bash
  sudo yum install gcc zlib-devel bzip2 bzip2-devel readline-devel sqlite \
      sqlite-devel openssl-devel xz xz-devel libffi-devel
  ```

b. Install and configure pyenv. This script will install pyenv and set up the necessary shell environment variables.

```bash
# Install pyenv
curl https://pyenv.run | bash

# Add pyenv to your shell's startup file (e.g., ~/.bashrc)
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# Restart your shell or run 'source ~/.bashrc' for changes to take effect
```

c. Install Python 3.11 (recommended for best compatibility). With pyenv installed, you can now install Python 3.11.

```bash
pyenv install 3.11
pyenv global 3.11
```

> ℹ️ **Note**: You can also use Python `3.9 ≤ version ≤ 3.13`, but Python 3.11 is recommended for optimal performance and compatibility.

### 🍎 macOS (Apple Silicon)

This guide is for users on macOS with Apple Silicon chips (M1, M2, M3, etc.).

> ⚠️ **Intel-based macOS devices are not supported.** If you're using an Intel Mac, run a Linux environment inside a Docker container (for example, Docker Desktop running an Ubuntu image) and follow the [Linux instructions](#-linux-x86_64--arm64) inside that container.

**1. Install System Dependencies**

We'll use Homebrew to install required packages like Python and LibOMP. This greatly simplifies the setup process.

* If you don't have Homebrew, run this command first:

  ```bash
  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  ```
* Once Homebrew is ready, install the dependencies:

  ```bash
  brew install virtualenv python@3.11 libomp
  ```

> ℹ️ Note: If you prefer not to use Homebrew, you must manually install Python 3.11, virtualenv, and libomp using an alternative method.

### ☁️ Google Colab

#### Using the enVector SDK in Google Colab

This guide explains how to install and use the enVector SDK in a Google Colab environment.\
**Note:** Official support for Colab will begin with version **1.0.3**, which is scheduled for release soon. Once available, you can easily install the SDK directly within a Colab notebook.

**1. How to Install (After Version 1.0.3 is Released)**

After the new version is published to PyPI, open a [Google Colab notebook](https://colab.research.google.com/) and run the following command in a code cell. The `!` prefix executes shell commands, and specifying the version ensures you get the Colab-compatible release.

```python
!pip install "pyenvector[colab]"
```

The `[colab]` suffix is an **extra dependency specifier**. It ensures that, in addition to the base `pyenvector` package, all **Colab-specific dependencies** are installed (e.g., additional packages or environment configurations needed for seamless operation in Google Colab).

* ✅ `pyenvector[colab]` → Installs the base package **along with synchronized Colab-specific dependencies**, ensuring compatibility in the Colab environment.
* ⚠️ `pyenvector` → Installs only the base package with potentially newer dependency versions, which may cause certain Colab-related functionality to be unavailable.

**2. Verify the Installation**

After the installation is complete, you can import and use the SDK in any subsequent cell. To confirm it's working correctly, run the following code:

```python
import pyenvector as ev

print("enVector SDK installed and imported successfully!")
print(f"Version: {ev.__version__}")
```

> ℹ️ **Note**: Google Colab runs in an isolated environment, so you don't need to create a virtual environment or worry about package conflicts.

## Common Installation Steps

Once you have Python and system dependencies installed on your platform, follow these common steps to complete the SDK installation.

> ℹ️ **Note**: Google Colab users can skip this section as they only need to run the pip install command.

### 1. Create and Activate a Virtual Environment

Using a virtual environment prevents conflicts with other Python projects.

1. Install `virtualenv` (if not already installed):

   ```bash
   pip install virtualenv
   ```
2. Create the environment using your Python version:

   ```bash
   # For Linux and macOS
   virtualenv -p python3.11 envector_venv
   ```
3. Activate the environment:

   ```bash
   source envector_venv/bin/activate
   ```

   > Your terminal prompt will now be prefixed with `(envector_venv)`.

### 2. Install the enVector SDK

Finally, install the SDK from PyPI using pip. This command will download and install the `pyenvector` package inside your active virtual environment.

```bash
pip install pyenvector
```

## Verification

After installation, you can verify that the SDK is working correctly by running:

```python
import pyenvector as ev

print("enVector SDK installed and imported successfully!")
print(f"Version: {ev.__version__}")
```

## Next Steps

Once you have the SDK installed, you can:

1. Generate your API key following the [Key Generation](/1.4.x/sdk-user-guide/key/key-generation.md) guide
2. Follow the [Quick Start](/1.4.x/get-started/quick-start.md) guide to begin using the SDK
3. Check out the API documentation for detailed usage examples

## Troubleshooting

If you encounter any issues during installation:

* Ensure you have a supported Python version installed:
  * **Linux** : Python `3.9 ≤ version ≤ 3.13`
  * **macOS**: Python `3.9 ≤ version ≤ 3.13`
* **Colab environment**
  * Make sure you include the Colab extras when installing:

    ```bash
    !pip install "pyenvector[colab]"
    ```
* Make sure you're using a virtual environment to avoid conflicts
* Check that all system dependencies are properly installed
* For Linux users, ensure pyenv is properly configured in your shell
* For macOS users, verify that Homebrew and libomp are correctly installed


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.envector.io/1.4.x/get-started/installation/client-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.