diff --git a/website/docs/docs/core/pip-install.md b/website/docs/docs/core/pip-install.md
index 6ed9ca06f8..9e35ee92d8 100644
--- a/website/docs/docs/core/pip-install.md
+++ b/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
-### 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`
+
+
+
+ 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
+ ```
+
+ 4. Run Python:
+
+ ```shell
+ env/bin/python
+ ```
+
+
+
+ 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
+ ```
+
+
+
+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
-2. Activate that same virtual environment each time you create a shell window or session:
+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.
diff --git a/website/package-lock.json b/website/package-lock.json
index 8d573ee342..c3699b6c20 100644
--- a/website/package-lock.json
+++ b/website/package-lock.json
@@ -5,6 +5,7 @@
"requires": true,
"packages": {
"": {
+ "name": "website",
"version": "0.0.0",
"dependencies": {
"@docusaurus/core": "3.4.0",
@@ -4949,9 +4950,10 @@
}
},
"node_modules/@stoplight/json-schema-viewer": {
- "version": "4.16.2",
- "resolved": "https://registry.npmjs.org/@stoplight/json-schema-viewer/-/json-schema-viewer-4.16.2.tgz",
- "integrity": "sha512-sOODscuidOTk9OMbE41XO5zt7DjKn6eoS32VtC5SJ0TbRT2vXfYVc9wrHLeae2YsNjsh98Nh+LaquGF504Ye2Q==",
+ "version": "4.16.4",
+ "resolved": "https://registry.npmjs.org/@stoplight/json-schema-viewer/-/json-schema-viewer-4.16.4.tgz",
+ "integrity": "sha512-5+2mQIhoFFPzk1Gxb1khrVk2Y5BzEIGcNnY74Ky0mo1ipkSNLBWX5ALU8Kn1rTjVjgO8KHacqR4rw/ZaNhxwhQ==",
+ "license": "Apache-2.0",
"dependencies": {
"@stoplight/json": "^3.20.1",
"@stoplight/json-schema-tree": "^4.0.0",
@@ -9902,9 +9904,10 @@
}
},
"node_modules/cross-spawn": {
- "version": "7.0.3",
- "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.3.tgz",
- "integrity": "sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w==",
+ "version": "7.0.6",
+ "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+ "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+ "license": "MIT",
"dependencies": {
"path-key": "^3.1.0",
"shebang-command": "^2.0.0",
@@ -11840,9 +11843,10 @@
}
},
"node_modules/express": {
- "version": "4.21.1",
- "resolved": "https://registry.npmjs.org/express/-/express-4.21.1.tgz",
- "integrity": "sha512-YSFlK1Ee0/GC8QaO91tHcDxJiE/X4FbpAyQWkxAvG6AXCuR65YzK8ua6D9hvi/TzUfZMpc+BwuM1IPw8fmQBiQ==",
+ "version": "4.21.2",
+ "resolved": "https://registry.npmjs.org/express/-/express-4.21.2.tgz",
+ "integrity": "sha512-28HqgMZAmih1Czt9ny7qr6ek2qddF4FclbMzwhCREB6OFfH+rXAnuNCwo1/wFvrtbgsQDb4kSbX9de9lFbrXnA==",
+ "license": "MIT",
"dependencies": {
"accepts": "~1.3.8",
"array-flatten": "1.1.1",
@@ -11863,7 +11867,7 @@
"methods": "~1.1.2",
"on-finished": "2.4.1",
"parseurl": "~1.3.3",
- "path-to-regexp": "0.1.10",
+ "path-to-regexp": "0.1.12",
"proxy-addr": "~2.0.7",
"qs": "6.13.0",
"range-parser": "~1.2.1",
@@ -11878,6 +11882,10 @@
},
"engines": {
"node": ">= 0.10.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
}
},
"node_modules/express/node_modules/content-disposition": {
@@ -11905,9 +11913,10 @@
"integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A=="
},
"node_modules/express/node_modules/path-to-regexp": {
- "version": "0.1.10",
- "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.10.tgz",
- "integrity": "sha512-7lf7qcQidTku0Gu3YDPc8DJ1q7OOucfa/BSsIwjuh56VU7katFvuM8hULfkwB3Fns/rsVF7PwPKVw1sl5KQS9w=="
+ "version": "0.1.12",
+ "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.12.tgz",
+ "integrity": "sha512-RA1GjUVMnvYFxuqovrEqZoxxW5NUZqbwKtYz/Tt7nXerk0LbLblQmrsgdeOxV5SFHf0UDggjS/bSeOZwt1pmEQ==",
+ "license": "MIT"
},
"node_modules/express/node_modules/range-parser": {
"version": "1.2.1",
@@ -21641,15 +21650,16 @@
}
},
"node_modules/nanoid": {
- "version": "3.3.7",
- "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.7.tgz",
- "integrity": "sha512-eSRppjcPIatRIMC1U6UngP8XFcz8MQWGQdt1MTBQ7NaAmvXDfvNxbvWV3x2y6CdEUciCSsDHDQZbhYaB8QEo2g==",
+ "version": "3.3.8",
+ "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.8.tgz",
+ "integrity": "sha512-WNLf5Sd8oZxOm+TzppcYk8gVOgP+l58xNy58D0nbUnOxOWRWvlcCV4kUF7ltmI6PsrLl/BgKEyS4mqsGChFN0w==",
"funding": [
{
"type": "github",
"url": "https://github.com/sponsors/ai"
}
],
+ "license": "MIT",
"bin": {
"nanoid": "bin/nanoid.cjs"
},
diff --git a/website/sidebars.js b/website/sidebars.js
index f120b6859b..c1b12f293e 100644
--- a/website/sidebars.js
+++ b/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",
],
},