A document explaining how to setup Python Virtual Environments (with examples for langchain 0.2)

python_virtual_environments__langchain02.md

Python Virtual Environments

What is a virtual environment?

A virtual environment (venv) is an isolated Python environment that allows you to install packages for a specific project without affecting your system Python or other projects.

Virtual environments are particularly useful when different projects require different versions of the same library.

For example, one project can use LangChain 0.2 while another uses a newer version, with no conflicts between their dependencies.

About this document

In this document we'll guide you through the steps to create and configure a virtual environment for projects that use LangChain v0.2.

If you need a venv for a different purpose, you can follow similar steps (make sure to adapt each step according to your specific use case).

Setup instructions

Open a terminal in your project directory and follow these steps.

1. Create a virtual environment

Pick a short name that describes the notebooks that will share it. Example: langchain-v0.2.

To create a virtual environment, you can use this command:

python -m venv .venv/langchain-v0.2

This creates a .venv/langchain-v0.2 folder. Replace langchain-v0.2 with your own name if you prefer.

2. Activate the environment

macOS / Linux:

source .venv/langchain-v0.2/bin/activate

Windows (PowerShell):

.\.venv\langchain-v0.2\Scripts\Activate.ps1

Once activated, the environment name will typically appear in your terminal prompt. You can verify that the correct environment is active by running python -c "import sys; print(sys.executable)".

3. Install the required packages

For example:

python -m pip install \
    "langchain<0.3" \
    "langchain-core<0.3" \
    "langchain-community<0.3" \
    "langchain-openai<0.2"

Replace the list of packages with the packages you need.

4. Register the environment as a Jupyter kernel (optional)

If you want to use the environment in Jupyter notebooks or VS Code notebooks, install ipykernel:

python -m pip install ipykernel

Then register the environment:

python -m ipykernel install \
    --user \
    --name langchain-v0.2 \
    --display-name "Python (LangChain 0.2)"

Explanation:

• --name is an internal id. Use the same name as the folder you created in the first step (in this case, langchain-v0.2).
• --display-name is the label you will see in the kernel list. You can change the text inside the quotes.

5. Select the environment in your notebook

Once you've created your virtual environment and registered it as a Jupyter kernel, you can select it whenever you want to run a notebook using that environment's Python interpreter and installed packages.

To do so, open your notebook in Jupyter or VS Code and follow these steps:

1. Open this notebook in your favourite environment (e.g., Jupyter or VS Code)
2. Select the Kernel you've just created
   • If you use Jupyter: Kernel → Change Kernel → Python (LangChain 0.2).
   • If you use VS Code: Click the Kernel selector in the top-right corner of the notebook editor → Jupyter Kernel → Python (LangChain 0.2)
     • Notice that you need to select "Jupyter Kernel" (not "Python Environments")
     • If "Python (LangChain 0.2)" doesn't appear in the kernel list, reload VS Code:
       • Press Cmd + Shift + P to open the Command Palette
       • Type Developer: Reload Window and press Enter
       • Try selecting the kernel again
3. Run the notebook as usual.

Deactivating a Virtual Environment

Deactivating a virtual environment means returning to your default Python environment in the terminal. You may want to do this when you're finished working on a project or when you want to switch to another environment.

To deactivate the current environment, run:

deactivate

Your virtual environment and installed packages remain unchanged, so you can reactivate it whenever you need it.

Best practices

• Isolate dependencies: Use a separate virtual environment for each project or set of dependencies to avoid version conflicts.
• Reuse existing environments: Create an environment once, then activate it whenever you return to the project.
• Use the correct Python interpreter: Activate the environment before installing packages or running scripts to ensure you use the project's dependencies.
• Track project dependencies: Save required packages in a requirements.txt file so you can recreate the environment when needed.
• Exclude environments from version control: Make sure to include the directory .venv in your .gitignore file, to prevent committing virtual environment files to Git.