How to create a virtualenv for Haystack

A Python virtual environment keeps a Haystack project's packages separate from the system interpreter and from other Python projects. That isolation matters when a retrieval pipeline needs Haystack plus optional integrations, because each project can pin its own packages without changing global Python state.

Haystack is installed from the haystack-ai package, and Python's venv module creates the local .venv directory for the project. A POSIX shell on Linux or macOS uses .venv/bin/activate; on Ubuntu or Debian, install the python3-venv operating system package first if python3 -m venv is not available.

Keep the virtualenv inside the project directory and install packages with python -m pip after activation. After installation, python -m pip show haystack-ai should report a package location under .venv, and import haystack should run from the activated Python process.

Steps to create a Haystack virtualenv:

Create a project directory.
```
$ mkdir haystack-project
```
Enter the project directory.
```
$ cd haystack-project
```
Check the Python version.
```
$ python3 --version
Python 3.14.4
```
The current haystack-ai package requires Python 3.10 or newer. Use the newer interpreter explicitly if your system's default python3 points to an older release.
Create the virtual environment.
```
$ python3 -m venv .venv
```
The .venv directory belongs to this project. Do not commit it to version control; recreate it from package requirements on other machines.
Activate the virtual environment.
```
$ source .venv/bin/activate
```
Your shell prompt may show (.venv) after activation.
Upgrade pip inside the virtualenv.
```
$ python -m pip install --upgrade pip
```
Using python -m pip keeps the install tied to the activated Python interpreter instead of whichever pip executable appears first in the shell path.
Install Haystack into the virtualenv.
```
$ python -m pip install haystack-ai
```
Optional integrations such as vector stores, model providers, or document converters are installed separately after the base haystack-ai package.

Confirm the package location is under the virtualenv.

$ python -m pip show haystack-ai
Name: haystack-ai
Version: 2.30.2
##### snipped #####
Location: /home/developer/haystack-project/.venv/lib/python3.14/site-packages
##### snipped #####

Import Haystack from the activated Python process.

$ python -c "import haystack; print(haystack.__version__)"
2.30.2