From cc9c6b6cfe49c6d9e6f84247b785ac08a2c808f5 Mon Sep 17 00:00:00 2001
From: Arcitec <38923130+Arcitec@users.noreply.github.com>
Date: Thu, 18 Sep 2025 18:51:43 +0200
Subject: [PATCH] docs: Clarify that UV handles Python and the environment
 creation

- Some users have been confused and were manually creating and activating Python venvs, which is not good since it can lead to the wrong Python version or dependency conflicts.

- Therefore, we add more detailed guidance to explain that `uv` manages the whole environment, the Python version, all dependencies and automatic environment activation.

- A few users were also confused about where `uv tool` installs binaries, but instead of explaining that in depth, we now add a link to the documentation page which explains how it works, and also instruct users to carefully read the `uv tool` output since it tells them how to add the installation to the system's path.
---
 README.md | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index fb26c46..6fc84f6 100644
--- a/README.md
+++ b/README.md
@@ -174,7 +174,8 @@ git lfs pull  # download large repository files
 4. Install required dependencies:
 
 We use `uv` to manage the project's dependency environment. The following command
-will install the correct versions of all dependencies into your `.venv` directory:
+will *automatically* create a `.venv` project-directory and then installs the correct
+versions of Python and all required dependencies:
 
 ```bash
 uv sync --all-extras
@@ -208,7 +209,7 @@ uv sync --all-extras --default-index "https://mirrors.tuna.tsinghua.edu.cn/pypi/
 > please ensure that you have installed NVIDIA's [CUDA Toolkit](https://developer.nvidia.com/cuda-toolkit)
 > version **12.8** (or newer) on your system.
 
-5. Download the required models:
+5. Download the required models via [uv tool](https://docs.astral.sh/uv/guides/tools/#installing-tools):
 
 Download via `huggingface-cli`:
 
@@ -226,14 +227,16 @@ uv tool install "modelscope"
 modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints
 ```
 
+> [!IMPORTANT]
+> If the commands above aren't available, please carefully read the `uv tool`
+> output. It will tell you how to add the tools to your system's path.
+
 > [!NOTE]
 > In addition to the above models, some small models will also be automatically
 > downloaded when the project is run for the first time. If your network environment
 > has slow access to HuggingFace, it is recommended to execute the following
 > command before running the code:
 > 
-> 除了以上模型外，项目初次运行时还会自动下载一些小模型，如果您的网络环境访问HuggingFace的速度较慢，推荐执行：
-> 
 > ```bash
 > export HF_ENDPOINT="https://hf-mirror.com"
 > ```
@@ -277,6 +280,10 @@ Have fun!
 > make it slower. The performance impact is highly dependent on your specific
 > hardware, drivers and operating system. Please try with and without it,
 > to discover what works best on your personal system.
+> 
+> Lastly, be aware that *all* `uv` commands will **automatically activate** the correct
+> per-project virtual environments. Do *not* manually activate any environments
+> before running `uv` commands, since that could lead to dependency conflicts!
 
 
 #### 📝 Using IndexTTS2 in Python