From 53c4ab7d29a9ac3e6621c3e4948610058ea296b0 Mon Sep 17 00:00:00 2001
From: ChloeAnn08 <chloeann27@gmail.com>
Date: Mon, 20 Oct 2025 19:23:58 -0400
Subject: [PATCH] Add virtual environment setup instructions to README

---
 README.md | 46 ++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 38 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index d58cdb7ff09..426a1ff6802 100644
--- a/README.md
+++ b/README.md
@@ -39,25 +39,50 @@ See our [architecture page](https://reflex.dev/blog/2024-03-21-reflex-architectu
 
 ## ⚙️ Installation
 
-Open a terminal and run (Requires Python 3.10+):
-
-```bash
-pip install reflex
-```
+**Important:** We strongly recommend using a virtual environment to ensure the `reflex` command is available in your PATH.
 
 ## 🥳 Create your first app
 
-Installing `reflex` also installs the `reflex` command line tool.
+### 1. Create the project directory
 
-Test that the install was successful by creating a new project. (Replace `my_app_name` with your project name):
+Replace `my_app_name` with your project name:
 
 ```bash
 mkdir my_app_name
 cd my_app_name
+```
+
+### 2. Set up a virtual environment
+
+Create and activate virtual environment
+
+```bash
+# On Windows:
+python -m venv .venv
+.venv\Scripts\activate
+
+# On macOS/Linux:
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+### 3. Install Reflex
+
+Reflex is available as a pip package (Requires Python 3.10+):
+
+```bash
+pip install reflex
+```
+
+### 4. Initialize the project
+
+This command initializes a template app in your new directory:
+
+```bash
 reflex init
 ```
 
-This command initializes a template app in your new directory.
+### 5. Run the app
 
 You can run this app in development mode:
 
@@ -69,6 +94,11 @@ You should see your app running at http://localhost:3000.
 
 Now you can modify the source code in `my_app_name/my_app_name.py`. Reflex has fast refreshes so you can see your changes instantly when you save your code.
 
+### Troubleshooting
+
+If you installed Reflex without a virtual environment and the `reflex` command is not found, you can run commands using: `python3 -m reflex init` and `python3 -m reflex run`
+
+
 ## 🫧 Example App
 
 Let's go over an example: creating an image generation UI around [DALL·E](https://platform.openai.com/docs/guides/images/image-generation?context=node). For simplicity, we just call the [OpenAI API](https://platform.openai.com/docs/api-reference/authentication), but you could replace this with an ML model run locally.