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", ], },