diff --git a/.github/workflows/build-publish.yml b/.github/workflows/build-publish.yml
index e8d0f75..9739950 100644
--- a/.github/workflows/build-publish.yml
+++ b/.github/workflows/build-publish.yml
@@ -35,6 +35,7 @@ jobs:
       run: |
         mv README.PyPI.md.stub README.PyPI.md
         tail -n +2 README.md >> README.PyPI.md
+        mv README.PyPI.md README.md
     - name: Build using Poetry
       run: |
         poetry build
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1d206d0..38fe458 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -29,10 +29,10 @@ and configurations are documented
 ### Prerequisites
 
 1. Download latest python from <https://www.python.org/downloads/>
-2. Install required libraries using below command.
+2. Once this repo is cloned install required libraries using:
 
    ```sh
-   pip install -r requirements.txt
+   pip install .
    ```
 
 ### GitHub Repository Clone
diff --git a/README.md b/README.md
index e4995cd..ccf2e9d 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,18 @@ Older versions of this package will of course remain available on
 
 ## Getting Started
 
+### 0. Use a virtual environment (venv)
+
+Modern Linux distributions don't like you using `pip` to install Python
+packages into the system namespace. So it's best to start with a virtual
+environment ([venv](https://docs.python.org/3/library/venv.html)).
+
+Even if you're using MacOS or Windows, it's highly recommended to start with a
+venv.
+
+We also suggest using [uv](https://docs.astral.sh/uv/) to create your venv and
+install stuff into it.
+
 ### 1. Installation
 
 This package can be installed from PyPI with:
@@ -36,7 +48,6 @@ pip install atsdk
 Alternatively clone this repo and from the repo root:
 
 ```shell
-pip install -r requirements.txt
 pip install .
 ```
 
diff --git a/pyproject.toml b/pyproject.toml
index fd434b0..ac9067c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -5,7 +5,7 @@ description = "Python SDK for atPlatform"
 authors = ["Umang Shah <shahumang19@gmail.com>","Chris Swan <chris@atsign.com>"]
 maintainers = ["Chris Swan <chris@atsign.com>"]
 license = "BSD-3-Clause"
-readme = "README.PyPI.md"
+readme = "README.md"
 packages = [{include = "at_client"}]
 homepage = "https://github.com/atsign-foundation/at_python"