Repository: dlt-hub/dlt
Pull request #2444: update dlt and dlt+ installations
Author: login: Soot3
Created: 2025-03-26T03:32:59Z | Merged: 2025-04-08T15:43:14Z

Only windows instructions had a line installing pip

Fixes #2299 @akelad 

<!--
Thank you for submitting a pull request! Please provide a brief description of your changes below.
-->
### Description


<!--
Please link any related issues. This helps us keep the PR focused and merge it faster.
-->
### Related Issues

- Fixes #...
- Closes #...
- Resolves #...

<!--
Provide any additional context about the PR here.
-->
### Additional Context
Updated the python 3.10 installation for ubuntu as well. Previously it gave module not found errors. Didnt end up adding uv as it adds steps to the commands e.g pip install dlt will become uv pip install dlt
<!--
Please ensure that
    - you have read the [Contributing to dlt](../CONTRIBUTING.md) guide.
    - you have run the tests locally and they have passed before submitting your PR.
-->


Linked issue #2299: Update dlt and dlt+ installation docs
### Documentation description

We noticed while writing the dlt+ installation docs that the Python instructions for Windows might be wrong - why does it tell you to install pip only for Windows? We should investigate/fix that.

And also, we should probably change or (add to) the environment instructions to use uv, because the current ones are a very old way of creating environments.

### Are you a dlt user?

None
Linked issue comments: user: login: Soot3
created_at: 2025-04-04T17:47:09Z
body: @akelad made a try at fixing this issue
author_association: CONTRIBUTOR

Diff:
diff --git a/docs/website/docs/plus/getting-started/installation.md b/docs/website/docs/plus/getting-started/installation.md
index 075b03d8a4..92ce147d7f 100644
--- a/docs/website/docs/plus/getting-started/installation.md
+++ b/docs/website/docs/plus/getting-started/installation.md
@@ -40,7 +40,7 @@ You can install Python 3.10 with `apt`.
 ```sh
 sudo apt update
 sudo apt install python3.10
-sudo apt install python3.10-venv
+pip install uv
 ```
 
   </TabItem>
@@ -51,6 +51,7 @@ On macOS, you can use [Homebrew](https://brew.sh) to install Python 3.10.
 ```sh
 brew update
 brew install python@3.10
+pip install uv
 ```
 
   </TabItem>
@@ -60,6 +61,7 @@ After installing [Python 3.10 (64-bit version) for Windows](https://www.python.o
 
 ```sh
 C:\> pip3 install -U pip
+C:\> pip3 install uv
 ```
 
   </TabItem>
@@ -74,46 +76,46 @@ This way, all the dependencies for your current project will be isolated from pa
 
   <TabItem value="ubuntu">
 
-Create a new virtual environment in your working folder. This will create an `./env` directory where your virtual environment will be stored:
+Create a new virtual environment in your working folder. This will create a `./venv` directory where your virtual environment will be stored:
 
 ```sh
-python -m venv ./env
+uv venv --python 3.10
 ```
 
 Activate the virtual environment:
 
 ```sh
-source ./env/bin/activate
+source .venv/bin/activate
 ```
 
   </TabItem>
   <TabItem value="macos">
 
-Create a new virtual environment in your working folder. This will create an `./env` directory where your virtual environment will be stored:
+Create a new virtual environment in your working folder. This will create a `./venv` directory where your virtual environment will be stored:
 
 ```sh
-python -m venv ./env
+uv venv --python 3.10
 ```
 
 Activate the virtual environment:
 
 ```sh
-source ./env/bin/activate
+source .venv/bin/activate
 ```
 
   </TabItem>
   <TabItem value="windows">
 
-Create a new virtual environment in your working folder. This will create an `./env` directory where your virtual environment will be stored:
+Create a new virtual environment in your working folder. This will create a `./venv` directory where your virtual environment will be stored:
 
 ```bat
-C:\> python -m venv ./env
+C:\> uv venv --python 3.10
 ```
 
 Activate the virtual environment:
 
 ```bat
-C:\> .\env\Scripts\activate
+C:\> .\venv\Scripts\activate
 ```
 
   </TabItem>
@@ -125,7 +127,7 @@ You can now install dlt+ in your virtual environment by running:
 
 ```sh
 # install the newest dlt version or upgrade the existing version to the newest one
-pip install -U dlt-plus
+uv pip install -U dlt-plus
 ```
 
 Please install a valid license before proceeding, as described under [licensing](#licensing).
diff --git a/docs/website/docs/reference/installation.md b/docs/website/docs/reference/installation.md
index 48966c813e..ce054e0da3 100644
--- a/docs/website/docs/reference/installation.md
+++ b/docs/website/docs/reference/installation.md
@@ -25,7 +25,7 @@ You can install Python 3.10 with `apt`.
 ```sh
 sudo apt update
 sudo apt install python3.10
-sudo apt install python3.10-venv
+pip install uv
 ```
 
   </TabItem>
@@ -36,6 +36,7 @@ On macOS, you can use [Homebrew](https://brew.sh) to install Python 3.10.
 ```sh
 brew update
 brew install python@3.10
+pip install uv
 ```
 
   </TabItem>
@@ -45,6 +46,7 @@ After installing [Python 3.10 (64-bit version) for Windows](https://www.python.o
 
 ```sh
 C:\> pip3 install -U pip
+C:\> pip3 install uv
 ```
 
   </TabItem>
@@ -59,46 +61,46 @@ This way, all the dependencies for your current project will be isolated from pa
 
   <TabItem value="ubuntu">
 
-Create a new virtual environment in your working folder. This will create an `./env` directory where your virtual environment will be stored:
+Create a new virtual environment in your working folder. This will create a `./venv` directory where your virtual environment will be stored:
 
 ```sh
-python -m venv ./env
+uv venv --python 3.10
 ```
 
 Activate the virtual environment:
 
 ```sh
-source ./env/bin/activate
+source .venv/bin/activate
 ```
 
   </TabItem>
   <TabItem value="macos">
 
-Create a new virtual environment in your working folder. This will create an `./env` directory where your virtual environment will be stored:
+Create a new virtual environment in your working folder. This will create a `./venv` directory where your virtual environment will be stored:
 
 ```sh
-python -m venv ./env
+uv venv --python 3.10
 ```
 
 Activate the virtual environment:
 
 ```sh
-source ./env/bin/activate
+source .venv/bin/activate
 ```
 
   </TabItem>
   <TabItem value="windows">
 
-Create a new virtual environment in your working folder. This will create an `./env` directory where your virtual environment will be stored:
+Create a new virtual environment in your working folder. This will create a `./venv` directory where your virtual environment will be stored:
 
 ```bat
-C:\> python -m venv ./env
+C:\> uv venv --python 3.10
 ```
 
 Activate the virtual environment:
 
 ```bat
-C:\> .\env\Scripts\activate
+C:\> .\venv\Scripts\activate
 ```
 
   </TabItem>
@@ -109,19 +111,19 @@ C:\> .\env\Scripts\activate
 To install or upgrade to the newest version of `dlt` in your virtual environment, run:
 
 ```sh
-pip install -U dlt
+uv pip install -U dlt
 ```
 
 Here are some additional installation examples:
 
 To install dlt with DuckDB support:
 ```sh
-pip install "dlt[duckdb]"
+uv pip install "dlt[duckdb]"
 ```
 
 To install a specific version of dlt (for example, versions before 0.5.0):
 ```sh
-pip install "dlt<0.5.0"
+uv pip install "dlt<0.5.0"
 ```
 
 ### 3.1. Install dlt via Pixi or Conda


Reviews:
user: login: sh-rp
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-08T08:44:41Z
user: login: sh-rp
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-08T08:47:36Z
user: login: Soot3
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-08T08:52:45Z
user: login: Soot3
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-08T08:56:11Z
user: login: akelad
body: Nice, thank you! I left some small comments, all of them also apply to the dlt+ page :) 
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-08T13:55:52Z
user: login: akelad
body: looks good to me!
state: DISMISSED
author_association: CONTRIBUTOR
submitted_at: 2025-04-08T15:35:08Z
user: login: akelad
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-08T15:38:36Z
user: login: akelad
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-08T15:39:19Z

Review comments:
diff_hunk: @@ -51,6 +54,7 @@ On macOS, you can use [Homebrew](https://brew.sh) to install Python 3.10.
 ```sh
 brew update
 brew install python@3.10
+python3.10 -m ensurepip --upgrade
path: docs/website/docs/plus/getting-started/installation.md
user: login: sh-rp
body: usually python should be available as the `python` command and you can use `pyenv` to manage multiple python versions and which one is active. Or is there a specific reason you add the python command with the version here?
created_at: 2025-04-08T08:44:41Z
author_association: COLLABORATOR
diff_hunk: @@ -23,9 +23,12 @@ If you have a different Python version installed or are missing pip, follow the
 You can install Python 3.10 with `apt`.
 
 ```sh
+sudo add-apt-repository ppa:deadsnakes/ppa
+sudo apt install -y software-properties-common
 sudo apt update
 sudo apt install python3.10
 sudo apt install python3.10-venv
+sudo apt install pip
path: docs/website/docs/reference/installation.md
user: login: sh-rp
body: I think pip should be installed automatically together with python, is that not the case?
created_at: 2025-04-08T08:47:35Z
author_association: COLLABORATOR
diff_hunk: @@ -51,6 +54,7 @@ On macOS, you can use [Homebrew](https://brew.sh) to install Python 3.10.
 ```sh
 brew update
 brew install python@3.10
+python3.10 -m ensurepip --upgrade
path: docs/website/docs/plus/getting-started/installation.md
user: login: Soot3
body: @sh-rp the instructions came with a specific version range  (Python 3.9-3.13) so I just made sure all commands used the newly installed python rather than a potentially lower version
created_at: 2025-04-08T08:52:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -23,9 +23,12 @@ If you have a different Python version installed or are missing pip, follow the
 You can install Python 3.10 with `apt`.
 
 ```sh
+sudo add-apt-repository ppa:deadsnakes/ppa
+sudo apt install -y software-properties-common
 sudo apt update
 sudo apt install python3.10
 sudo apt install python3.10-venv
+sudo apt install pip
path: docs/website/docs/reference/installation.md
user: login: Soot3
body: Not always. And the main issue was that only the windows instructions installed pip explicitly.
created_at: 2025-04-08T08:56:11Z
author_association: CONTRIBUTOR
diff_hunk: @@ -51,6 +51,7 @@ On macOS, you can use [Homebrew](https://brew.sh) to install Python 3.10.
 ```sh
 brew update
 brew install python@3.10
+brew install uv
path: docs/website/docs/plus/getting-started/installation.md
user: login: akelad
body: ```suggestion
pip install uv
```
created_at: 2025-04-08T13:38:50Z
author_association: CONTRIBUTOR
diff_hunk: @@ -51,6 +51,7 @@ On macOS, you can use [Homebrew](https://brew.sh) to install Python 3.10.
 ```sh
 brew update
 brew install python@3.10
+brew install uv
path: docs/website/docs/plus/getting-started/installation.md
user: login: akelad
body: you're also missing the `pip install uv` part for Windows - please add it! 
created_at: 2025-04-08T13:41:36Z
author_association: CONTRIBUTOR
diff_hunk: @@ -51,6 +51,7 @@ On macOS, you can use [Homebrew](https://brew.sh) to install Python 3.10.
 ```sh
 brew update
 brew install python@3.10
+brew install uv
path: docs/website/docs/plus/getting-started/installation.md
user: login: akelad
body: Same comments for the dlt+ docs btw! 
created_at: 2025-04-08T13:50:54Z
author_association: CONTRIBUTOR
diff_hunk: @@ -74,46 +75,46 @@ This way, all the dependencies for your current project will be isolated from pa
 
   <TabItem value="ubuntu">
 
-Create a new virtual environment in your working folder. This will create an `./env` directory where your virtual environment will be stored:
+Create a new virtual environment in your working folder. This will create an `./venv` directory where your virtual environment will be stored:
path: docs/website/docs/plus/getting-started/installation.md
user: login: akelad
body: ```suggestion
Create a new virtual environment in your working folder. This will create a `./venv` directory where your virtual environment will be stored:
```
created_at: 2025-04-08T13:54:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -60,6 +61,7 @@ After installing [Python 3.10 (64-bit version) for Windows](https://www.python.o
 
 ```sh
 C:\> pip3 install -U pip
+C:\> pip install uv
path: docs/website/docs/plus/getting-started/installation.md
user: login: akelad
body: ```suggestion
C:\> pip3 install uv
```
created_at: 2025-04-08T15:38:16Z
author_association: CONTRIBUTOR
diff_hunk: @@ -45,6 +46,7 @@ After installing [Python 3.10 (64-bit version) for Windows](https://www.python.o
 
 ```sh
 C:\> pip3 install -U pip
+C:\> pip install uv
path: docs/website/docs/reference/installation.md
user: login: akelad
body: ```suggestion
C:\> pip3 install uv
```
created_at: 2025-04-08T15:38:33Z
author_association: CONTRIBUTOR

PR comments:
user: login: netlify[bot]
created_at: 2025-03-26T03:33:17Z
body: ### <span aria-hidden="true">✅</span> Deploy Preview for *dlt-hub-docs* ready!


|  Name | Link |
|:-:|------------------------|
|<span aria-hidden="true">🔨</span> Latest commit | 2538af4e6c0c143f25b78020057c7e49bf79ff6f |
|<span aria-hidden="true">🔍</span> Latest deploy log | https://app.netlify.com/sites/dlt-hub-docs/deploys/67f543165cd9f800084de809 |
|<span aria-hidden="true">😎</span> Deploy Preview | [https://deploy-preview-2444--dlt-hub-docs.netlify.app](https://deploy-preview-2444--dlt-hub-docs.netlify.app) |
|<span aria-hidden="true">📱</span> Preview on mobile | <details><summary> Toggle QR Code... </summary><br /><br />![QR Code](https://app.netlify.com/qr-code/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1cmwiOiJodHRwczovL2RlcGxveS1wcmV2aWV3LTI0NDQtLWRsdC1odWItZG9jcy5uZXRsaWZ5LmFwcCJ9.J8Gt0uOKd3YPuFXPjkJ5VOCynh6xJtht2zES9V6f6bk)<br /><br />_Use your smartphone camera to open QR code link._</details> |
---
<!-- [dlt-hub-docs Preview](https://deploy-preview-2444--dlt-hub-docs.netlify.app) -->
_To edit notification comments on pull requests, go to your [Netlify site configuration](https://app.netlify.com/sites/dlt-hub-docs/configuration/notifications#deploy-webhooks)._
author_association: NONE
user: login: akelad
created_at: 2025-04-08T09:12:02Z
body: Hi @Soot3 thanks for the PR! I think there's a small misunderstanding with the issue though. There were two things in there:
* We wanted to validate whether you need to explicitly install pip on Windows (based on our own research, it seems that you do sometimes), the instructions for Mac/Ubuntu don't need to change.
* We should replace the instructions for a virtual environment to use `uv` instead. There's an example of how that might look like [here](https://rasa.com/docs/pro/installation/python#virtual-environment-setup)

So the only thing that needs to be done is the second part about the virtual environment - if you want to take that on, we'd be happy to accept that as a contribution :) 
author_association: CONTRIBUTOR
user: login: Soot3
created_at: 2025-04-08T09:16:29Z
body: Okay then. Let me change the commit. Thank you @akelad 
author_association: CONTRIBUTOR
user: login: Soot3
created_at: 2025-04-08T15:30:37Z
body: @akelad  fixed. Thank you
author_association: CONTRIBUTOR
user: login: akelad
created_at: 2025-04-08T15:44:36Z
body: Thanks again for the submission @Soot3! 
author_association: CONTRIBUTOR