Create a Python virtual environment

website/docs/docs/core/pip-install.md

@@ -10,24 +10,98 @@ You can install dbt Core and plugins using `pip` because they are Python modules
 <FAQ path="Core/install-pip-os-prereqs" />
 <FAQ path="Core/install-python-compatibility" />
 
-### Using virtual environments
+## What is a Python virtual environment?
 
-We recommend using virtual environments (venv) to namespace pip modules.
+A Python virtual environment creates an isolated workspace for Python projects, preventing conflicts between dependencies of different projects and versions.
 
-1. Create a new venv:
+You can create virtual environments using tools like [conda](https://anaconda.org/anaconda/conda), [poetry](https://python-poetry.org/docs/managing-environments/) or `venv`. This guide uses `venv` because it's lightweight, has the fewest additional dependencies, and is included in Python by default.
 
-```shell
-python -m venv dbt-env				# create the environment
-```
+Users who want to run dbt locally, for example in [dbt Core](/docs/core/installation-overview) or the [dbt Cloud CLI](/docs/cloud/cloud-cli-installation#install-a-virtual-environment) may want to install a Python virtual environment.
+
+### Prerequisites
+
+Once you've met the prerequisites, follow these steps to set up your virtual environment.
+
+- Access to a terminal or command prompt.
+- Have [Python](https://www.python.org/downloads/) installed on your machine. You can check if Python is installed by running `python --version` or `python3 --version` in your terminal or command prompt.
+- Have [pip installed](https://pip.pypa.io/en/stable/installation/). You can check if pip is installed by running `pip --version` or `pip3 --version`.
+- Have the necessary permissions to create directories and install packages on your machine.
+
+### Set up a Python virtual environment 
+
+`venv` will set up a Python virtual environment within the `env` folder.
+
+Depending on the operating system you use, you'll need to execute specific steps to set up a virtual environment. 
+
+To set up a Python virtual environment, navigate to your project directory and execute the command. This will generate a new virtual environment within a local folder that you can name anything.  [Our convention](https://github.com/dbt-labs/dbt-core/blob/main/CONTRIBUTING.md#virtual-environments) has been to name it `env` or `env-anything-you-want`
+
+<Tabs>
+  <TabItem value="Unix/macOS" label="Unix/macOS">
+    1. Create your virtual environment:
+
+    ```shell
+    python3 -m venv env
+    ```
+
+    2. Activate your virtual environment:
+
+    ```shell
+    source env/bin/activate
+    ```
+
+    3. Verify Python Path:
+
+    ```shell
+    which python
+    ```
 
-2. Activate that same virtual environment each time you create a shell window or session:
+    4. Run Python:
+
+    ```shell
+    env/bin/python
+    ```
+  </TabItem>
+
+  <TabItem value="Windows" label="Windows">
+    1. Create your virtual environment
+
+    ```shell
+    py -m venv env
+    ```
+
+    2. Activate your virtual environment:
+
+    ```shell
+    env\Scripts\activate
+    ```
+
+    3. Verify Python Path:
+
+    ```shell
+    where python
+    ```
+
+    4. Run Python:
+
+    ```shell
+    env\Scripts\python
+    ```
+  </TabItem>
+</Tabs>
+
+If you're using dbt Core, refer to [What are the best practices for installing dbt Core with pip?](/faqs/Core/install-pip-best-practices.md#using-virtual-environments) after creating your virtual environment. 
+
+If you're using the dbt Cloud CLI, you can [install dbt Cloud CLI in pip](/docs/cloud/cloud-cli-installation#install-dbt-cloud-cli-in-pip) after creating your virtual environment.
+
+### Deactivate virtual environment
+
+To switch projects or leave your virtual environment, deactivate the environment using the command while the virtual environment is active:
 
 ```shell
-source dbt-env/bin/activate			# activate the environment for Mac and Linux OR
-dbt-env\Scripts\activate			# activate the environment for Windows
+deactivate
 ```
 
-#### Create an alias
+### Create an alias
 
 To activate your dbt environment with every new shell window or session, you can create an alias for the source command in your `$HOME/.bashrc`, `$HOME/.zshrc`, or whichever config file your shell draws from. 
 
@@ -37,7 +111,7 @@ For example, add the following to your rc file, replacing `<PATH_TO_VIRTUAL_ENV_
 alias env_dbt='source <PATH_TO_VIRTUAL_ENV_CONFIG>/bin/activate'
 ```
 
-### Installing the adapter
+## Installing the adapter
 
 Once you decide [which adapter](/docs/supported-data-platforms) you're using, you can install using the command line. Beginning in v1.8, installing an adapter does not automatically install `dbt-core`. This is because adapters and dbt Core versions have been decoupled from each other so we no longer want to overwrite existing dbt-core installations.
 
@@ -119,7 +193,7 @@ If you're building a tool that integrates with dbt Core, you may want to install
 python -m pip install dbt-core
 ```
 
-### Change dbt Core versions
+## Change dbt Core versions
 
 You can upgrade or downgrade versions of dbt Core by using the `--upgrade` option on the command line (CLI). For more information, see [Best practices for upgrading in Core versions](/docs/dbt-versions/core#best-practices-for-upgrading).
 
@@ -135,7 +209,7 @@ To downgrade to an older version, specify the version you want to use. This comm
 python -m pip install --upgrade dbt-core==0.19.0
 ```
 
-### `pip install dbt`
+## `pip install dbt`
 
 Note that, as of v1.0.0, `pip install dbt` is no longer supported, will raise an explicit error, and the `dbt` package on PyPI stopped receiving updates. Since v0.13, PyPI package named `dbt` was a simple "pass-through" of dbt-core and the four original database adapter plugins.
 
@@ -157,7 +231,7 @@ Or, better yet, just install the package(s) you need!
 
 <VersionBlock firstVersion="1.8">
 
-### Installing prereleases
+## Installing prereleases
 
 A prerelease adapter is a version released before the final, stable version. It allows users to test new features, provide feedback, and get early access to upcoming functionality &mdash; ensuring your system will be ready for the final release.
 
@@ -192,7 +266,7 @@ dbt --version
 ```
 Note, this will also install any pre-releases of all dependencies.
 
-#### Activate your virtual environment 
+### Activate your virtual environment 
 
 To install or use packages within your virtual environment:
 

website/sidebars.js

@@ -194,8 +194,8 @@ const sidebarSettings = {
               link: { type: "doc", id: "docs/core/installation-overview" },
               items: [
                 "docs/core/installation-overview",
-                "docs/core/pip-install",
                 "docs/core/docker-install",
+                "docs/core/pip-install",
                 "docs/core/source-install",
               ],
             },