From 96b84f8db89e3ebda58a76572a9d14a258a2f42c Mon Sep 17 00:00:00 2001
From: Hariharan Balakrishnan
 <115121629+HariharanBalakrishnan22@users.noreply.github.com>
Date: Tue, 22 Apr 2025 14:17:02 -0700
Subject: [PATCH] Docs: Improve installation section and add troubleshooting
 guide

---
 README.md | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7d080b8bb..147598f8e 100644
--- a/README.md
+++ b/README.md
@@ -60,9 +60,11 @@ Preswald tracks state and dependencies, so computations update only when needed
 
 # **🚀 Getting Started**
 
+```markdown
 ## **Installation**
 
-First, install Preswald using pip. https://pypi.org/project/preswald/
+First, install Preswald using pip (requires Python 3.7+)  
+[Preswald on PyPI](https://pypi.org/project/preswald/)
 
 ```bash
 pip install preswald
@@ -72,6 +74,12 @@ or
 uv pip install preswald
 ```
 
+**Note:**  
+If you encounter issues during installation, make sure you have an updated version of pip:
+
+```bash
+pip install --upgrade pip
+
 ![Demo GIF](assets/demo1.gif)
 
 ## **👩‍💻 Quick Start**
@@ -158,6 +166,7 @@ The first time you deploy, you'll be prompted to enter your **GitHub username**
 Now your app is live, shareable, and scalable—without any extra setup.
 
 
+
 ## **🔧 Configuration**
 
 Preswald uses `preswald.toml` for project settings and theming. It’s straightforward, and it makes your app look polished.
@@ -189,6 +198,25 @@ format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
 
 <br>
 
+## 🛠 Troubleshooting
+
+### Port already in use
+
+If you run `preswald run` and see an error like:
+```
+OSError: [Errno 98] Address already in use
+```
+it means another application is already using the default port (8501).
+
+You have two options:
+- Stop the application that's using port 8501
+- Or run Preswald on a different port:
+
+```bash
+preswald run --port 8502
+
+
+
 ## **📚 Documentation**
 
 We’re here to help! Check out our full documentation at [Preswald Docs](https://docs.preswald.com/).