> ## Documentation Index
> Fetch the complete documentation index at: https://fastapi2day.codewithsiva.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Virtual Environments: Isolation Per Project

> Understand why virtual environments are essential in Python, and learn to create and activate a .venv for every project using VS Code or the terminal.

One of the first habits every serious Python developer builds is creating a virtual environment for every project. Without one, all the packages you install across all your projects pile up in a single shared Python installation — and that shared space quickly leads to version conflicts, broken projects, and debugging sessions that are very hard to trace. Virtual environments eliminate this problem entirely by giving each project its own isolated Python instance with its own package directory.

## Why isolation matters

Imagine you are maintaining two Python projects simultaneously:

* **Project A** depends on version `1.0` of a library
* **Project B** requires version `2.0` of the same library, which changed its API

If both projects share the same Python installation, upgrading the library for Project B breaks Project A. There is no clean way to resolve this without isolation.

A virtual environment solves this by creating a self-contained copy of Python for each project. Installing a package into Project A's environment has zero effect on Project B's environment.

<Note>
  Create a new virtual environment for every Python project you start — no exceptions. This is a universal best practice in professional Python development, and it will save you significant debugging time.
</Note>

## What a virtual environment contains

When you create a virtual environment (conventionally named `.venv`), Python creates a folder with three things:

1. A copy of the Python interpreter
2. A `site-packages` directory where installed packages live
3. Activation scripts that switch your shell to use this environment

Your project structure will look like this:

```
python-for-ai/
├── .venv/                  # The virtual environment (hidden folder)
│   ├── bin/                # Python executable and activation scripts (macOS/Linux)
│   ├── Scripts/            # Python executable and activation scripts (Windows)
│   └── lib/                # Installed packages live here
├── hello.py
└── python-for-ai.code-workspace
```

<Note>
  The leading dot in `.venv` makes it a hidden folder on macOS and Linux. You rarely need to look inside it — just let VS Code manage it.
</Note>

## Create a virtual environment

You have two ways to create a virtual environment. The VS Code method is easier; the terminal method is useful when you need more control.

### Method 1: VS Code Command Palette (recommended for beginners)

<Steps>
  <Step title="Open the Command Palette">
    Press `Ctrl/Cmd + Shift + P`.
  </Step>

  <Step title="Create the environment">
    Type **Python: Create Environment** and press `Enter`.
  </Step>

  <Step title="Choose Venv">
    Select **Venv** when asked for the environment type.
  </Step>

  <Step title="Select your Python installation">
    Choose the Python version you installed earlier.
  </Step>
</Steps>

VS Code creates the `.venv` folder and automatically selects it as the interpreter for your project.

### Method 2: Terminal command

<Steps>
  <Step title="Open the terminal">
    Press `` Ctrl + ` `` (Windows/Linux) or `` Cmd + ` `` (macOS), or go to **View → Terminal**.
  </Step>

  <Step title="Navigate to your project folder">
    Make sure you are inside `python-for-ai/` before running the next command.
  </Step>

  <Step title="Create the environment">
    <CodeGroup>
      ```bash Windows theme={null}
      python -m venv .venv
      ```

      ```bash macOS / Linux theme={null}
      python3 -m venv .venv
      ```
    </CodeGroup>
  </Step>
</Steps>

## Activate the virtual environment in VS Code

Creating the environment is only half the job — you also need to make VS Code use it.

<Steps>
  <Step title="Open the Command Palette">
    Press `Ctrl/Cmd + Shift + P`.
  </Step>

  <Step title="Select the interpreter">
    Type **Python: Select Interpreter** and press `Enter`.
  </Step>

  <Step title="Choose .venv">
    Select the interpreter that shows `.venv` in its path (something like `./.venv/bin/python`).
  </Step>
</Steps>

Once selected, VS Code activates the environment automatically every time you open a new terminal in this project. You will see `(.venv)` at the start of your terminal prompt:

```bash theme={null}
(.venv) ~/python-for-ai $
```

<Tip>
  This is the recommended workflow. VS Code remembers your interpreter choice per workspace, so you never have to reactivate manually — just open the project and the environment is already active.
</Tip>

## Manually activating from the terminal

If you ever need to activate the environment in a terminal outside of VS Code, here are the commands:

<CodeGroup>
  ```bash Windows (PowerShell) theme={null}
  .venv\Scripts\Activate.ps1
  ```

  ```bash Windows (Command Prompt) theme={null}
  .venv\Scripts\activate.bat
  ```

  ```bash macOS / Linux theme={null}
  source .venv/bin/activate
  ```
</CodeGroup>

To deactivate and return to the system Python:

```bash theme={null}
deactivate
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Command not found: python -m venv" icon="circle-exclamation">
    On Ubuntu or Debian, the `venv` module is sometimes distributed separately:

    ```bash theme={null}
    sudo apt install python3-venv
    ```

    On other systems it is included with Python by default.
  </Accordion>

  <Accordion title="Permission denied on activation" icon="lock">
    On macOS/Linux, make the activation script executable:

    ```bash theme={null}
    chmod +x .venv/bin/activate
    ```
  </Accordion>

  <Accordion title="VS Code does not recognise the virtual environment" icon="code">
    1. Press `Ctrl/Cmd + Shift + P` → **Developer: Reload Window**
    2. Then press `Ctrl/Cmd + Shift + P` → **Python: Select Interpreter** again
    3. Confirm the Python and Jupyter extensions are both installed
  </Accordion>
</AccordionGroup>

## A note on Anaconda

Anaconda is an alternative Python distribution popular in data science circles. It comes pre-loaded with many scientific packages and includes its own environment manager (`conda`).

Unless your workplace specifically requires Anaconda, stick with standard Python virtual environments. They are lighter, faster to create, and work seamlessly with every tool and tutorial you will encounter in modern Python development.

<Card title="Python packages" icon="box" href="/getting-started/packages-and-pip">
  Learn how to install packages with pip inside your virtual environment.
</Card>