diff --git a/docs/contributing.rst b/docs/contributing.rst
index f36130f4b..f06afe7cc 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -19,6 +19,10 @@ Next, install the development dependencies and set up the project. We recommend
 virtual environment, such as `virtualenv <https://virtualenv.pypa.io/en/stable/>`_ or
 Python's built-in ``venv`` module. Instructions vary by platform:
 
+.. note::
+
+    py-libp2p contributor setup is currently supported on Python versions ``<= 3.13``.
+
 Linux Setup
 ^^^^^^^^^^^
 
@@ -47,10 +51,13 @@ Install the development dependencies using a virtual environment:
 .. code:: sh
 
     cd py-libp2p
-    python3 -m venv ./venv
-    . venv/bin/activate
     ./scripts/setup_dev.sh
 
+.. note::
+
+    On Linux, if you are not already in a virtual environment, the script will create one
+    automatically and instruct you to activate it.
+
 **Option 2: Using uv (recommended, same as CI):**
 
 First, install ``uv`` if you haven't already:
@@ -70,19 +77,16 @@ Then set up the development environment:
 .. code:: sh
 
     cd py-libp2p
-    uv venv venv
-    source venv/bin/activate
-    uv pip install --upgrade pip
-    uv pip install --group dev -e .
-    pre-commit install
+    uv sync --group dev
+    uv run pre-commit install
 
 **Option 3: Manual setup with pip:**
 
 .. code:: sh
 
     cd py-libp2p
-    python3 -m venv ./venv
-    . venv/bin/activate
+    python3 -m venv .venv
+    . .venv/bin/activate
     pip install --upgrade pip  # Ensure pip >= 25.1 for PEP 735 support
     pip install --group dev -e .
     pre-commit install
@@ -95,8 +99,8 @@ An alternative using ``virtualenv``:
 .. code:: sh
 
     cd py-libp2p
-    virtualenv -p python venv
-    . venv/bin/activate
+    virtualenv -p python .venv
+    . .venv/bin/activate
     pip install --upgrade pip  # Ensure pip >= 25.1 for PEP 735 support
     pip install --group dev -e .
     pre-commit install
@@ -129,8 +133,6 @@ Install the development dependencies using a virtual environment:
 .. code:: sh
 
     cd py-libp2p
-    python3 -m venv ./venv
-    . venv/bin/activate
     ./scripts/setup_dev.sh
 
 **Option 2: Using uv (recommended, same as CI):**
@@ -158,36 +160,20 @@ Then set up the development environment:
 .. code:: sh
 
     cd py-libp2p
-    uv venv venv
-    source venv/bin/activate
-    uv pip install --upgrade pip
-    uv pip install --group dev -e .
-    pre-commit install
-
-On macOS, help the build command find and link against the ``gmp`` library:
-
-.. code:: sh
-
-    CFLAGS="`pkg-config --cflags gmp`" LDFLAGS="`pkg-config --libs gmp`" uv pip install --group dev -e .
+    CFLAGS="$(pkg-config --cflags gmp)" LDFLAGS="$(pkg-config --libs gmp)" uv sync --group dev
+    uv run pre-commit install
 
 **Option 3: Manual setup with pip:**
 
 .. code:: sh
 
     cd py-libp2p
-    python3 -m venv ./venv
-    . venv/bin/activate
+    python3 -m venv .venv
+    . .venv/bin/activate
     pip install --upgrade pip  # Ensure pip >= 25.1 for PEP 735 support
-    pip install --group dev -e .
+    CFLAGS="$(pkg-config --cflags gmp)" LDFLAGS="$(pkg-config --libs gmp)" pip install --group dev -e .
     pre-commit install
 
-On macOS, help the build command find and link against the ``gmp`` library:
-
-.. code:: sh
-
-    pip install --upgrade pip  # Ensure pip >= 25.1 for PEP 735 support
-    CFLAGS="`pkg-config --cflags gmp`" LDFLAGS="`pkg-config --libs gmp`" pip install --group dev -e .
-
 **Note:** This project uses PEP 735 ``[dependency-groups]`` which requires pip >= 25.1.
 If you have an older pip version, upgrade it first.
 
@@ -196,8 +182,8 @@ An alternative using ``virtualenv``:
 .. code:: sh
 
     cd py-libp2p
-    virtualenv -p python venv
-    . venv/bin/activate
+    virtualenv -p python .venv
+    . .venv/bin/activate
     pip install --upgrade pip  # Ensure pip >= 25.1 for PEP 735 support
     pip install --group dev -e .
     pre-commit install
@@ -282,11 +268,8 @@ Setup Steps
 
    .. code:: powershell
 
-        uv venv venv
-        .\venv\Scripts\activate
-        uv pip install --upgrade pip
-        uv pip install --group dev -e .
-        pre-commit install
+        uv sync --group dev
+        uv run pre-commit install
 
    **Option B: Using pip:**
 
diff --git a/docs/install.rst b/docs/install.rst
index c94b5cd9d..ef4a644d2 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -3,6 +3,10 @@ Install
 
 Follow the steps below to install `py-libp2p` on your platform.
 
+.. note::
+
+    py-libp2p installation is currently supported on Python versions ``<= 3.13``.
+
 Using uv (recommended)
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -21,17 +25,20 @@ It is used in py-libp2p's CI/CD pipeline and is the recommended way to install.
 
        pip install uv
 
-2. Create and activate a virtual environment:
+2. Create a virtual environment and install `py-libp2p`:
 
    .. code:: sh
 
-       uv venv .venv
+       uv sync
+
+   This automatically creates a ``.venv`` in the project directory and installs
+   the package. Activate the environment to use it:
 
    - **Linux / macOS**
 
      .. code:: sh
 
-         source .venv/bin/activate
+         . .venv/bin/activate
 
    - **Windows (PowerShell)**
 
@@ -39,12 +46,6 @@ It is used in py-libp2p's CI/CD pipeline and is the recommended way to install.
 
          .venv\Scripts\Activate.ps1
 
-3. Install `py-libp2p`:
-
-   .. code:: sh
-
-       uv pip install libp2p
-
 Using pip
 ~~~~~~~~~
 
@@ -62,7 +63,7 @@ If you prefer pip, you can install `py-libp2p` the traditional way:
 
      .. code:: sh
 
-         source .venv/bin/activate
+         . .venv/bin/activate
 
    - **Windows (cmd)**
 
@@ -85,21 +86,14 @@ If you prefer pip, you can install `py-libp2p` the traditional way:
 Development Installation
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-To install for development with all dev dependencies:
+To install for development with all dev dependencies, use the ``dev`` dependency group:
 
 .. code:: sh
 
-    # Using uv (recommended)
-    uv pip install --group dev -e .
-
-    # Or using pip
-    pip install --group dev -e .
+    uv sync --group dev
 
-py-libp2p uses `dependency groups <https://peps.python.org/pep-0735/>`_ (PEP 735)
-for dev dependencies, so the `--group dev` flag is required.
-If you use pip for development installation, ensure pip >= 25.1 so `--group`
-is available.
-For full contributor environment setup, see :doc:`contributing`.
+For the full contributor environment setup (including pre-commit hooks), see
+:doc:`contributing`.
 
 Usage
 -----
diff --git a/newsfragments/1248.docs.rst b/newsfragments/1248.docs.rst
new file mode 100644
index 000000000..0b0029df1
--- /dev/null
+++ b/newsfragments/1248.docs.rst
@@ -0,0 +1 @@
+Updated contributor setup documentation to use ``uv sync`` with the default ``.venv`` workflow, including clearer setup-script guidance for Linux and macOS.
diff --git a/scripts/setup_dev.sh b/scripts/setup_dev.sh
index dd8db22fd..6800fb4ef 100755
--- a/scripts/setup_dev.sh
+++ b/scripts/setup_dev.sh
@@ -12,39 +12,49 @@ NC='\033[0m' # No Color
 
 echo -e "${GREEN}Setting up py-libp2p development environment...${NC}"
 
-# Check if we're in a virtual environment
-if [[ -z "$VIRTUAL_ENV" ]]; then
-    echo -e "${YELLOW}Warning: Not in a virtual environment. Creating one...${NC}"
-    python3 -m venv venv
-    echo -e "${GREEN}Virtual environment created. Activate it with:${NC}"
-    echo -e "  source venv/bin/activate"
-    echo -e "${YELLOW}Then run this script again.${NC}"
-    exit 1
-fi
-
-# Check pip version
-PIP_VERSION=$(pip --version | grep -oE '[0-9]+\.[0-9]+' | head -1)
-PIP_MAJOR=$(echo $PIP_VERSION | cut -d. -f1)
-PIP_MINOR=$(echo $PIP_VERSION | cut -d. -f2)
-
-# PEP 735 dependency-groups support requires pip >= 25.1
-if [ "$PIP_MAJOR" -lt 25 ] || ([ "$PIP_MAJOR" -eq 25 ] && [ "$PIP_MINOR" -lt 1 ]); then
-    echo -e "${YELLOW}Upgrading pip to support PEP 735 dependency-groups...${NC}"
-    pip install --upgrade pip
-fi
-
-# Check if uv is available (preferred method used in CI)
+# Check if uv is available
 if command -v uv &> /dev/null; then
     echo -e "${GREEN}Using uv for installation (recommended)...${NC}"
-    uv pip install --upgrade pip
-    uv pip install --group dev -e .
+    # if on macOS, add gmp flags to the sync command
+    if [[ "$(uname -s)" == "Darwin" ]]; then
+        CFLAGS="$(pkg-config --cflags gmp)" LDFLAGS="$(pkg-config --libs gmp)" uv sync --group dev
+    else
+        uv sync --group dev
+    fi
+
+    # Install pre-commit hooks
+    echo -e "${GREEN}Installing pre-commit hooks...${NC}"
+    uv run pre-commit install
+
+    echo -e "${GREEN}Setup complete! You can now run 'make pr' to check your changes, or 'make docs' to build the docs.${NC}"
 else
+    # Check if virtual environment flag is set
+    if [[ -z "$VIRTUAL_ENV" ]]; then
+        echo -e "${YELLOW}Warning: Not in a virtual environment. Creating one...${NC}"
+        python3 -m venv .venv
+        echo -e "${GREEN}Virtual environment created. Activate it with:${NC}"
+        echo -e "  . .venv/bin/activate"
+        echo -e "${YELLOW}Then run this script again.${NC}"
+        exit 1
+    fi
+
+    # Check pip version
+    PIP_VERSION=$(pip --version | grep -oE '[0-9]+\.[0-9]+' | head -1)
+    PIP_MAJOR=$(echo $PIP_VERSION | cut -d. -f1)
+    PIP_MINOR=$(echo $PIP_VERSION | cut -d. -f2)
+
+    # PEP 735 dependency-groups support requires pip >= 25.1
+    if [ "$PIP_MAJOR" -lt 25 ] || ([ "$PIP_MAJOR" -eq 25 ] && [ "$PIP_MINOR" -lt 1 ]); then
+        echo -e "${YELLOW}Upgrading pip to support PEP 735 dependency-groups...${NC}"
+        pip install --upgrade pip
+    fi
+
     echo -e "${GREEN}Using pip for installation...${NC}"
     pip install --group dev -e .
-fi
 
-# Install pre-commit hooks
-echo -e "${GREEN}Installing pre-commit hooks...${NC}"
-pre-commit install
+    # Install pre-commit hooks
+    echo -e "${GREEN}Installing pre-commit hooks...${NC}"
+    pre-commit install
 
-echo -e "${GREEN}Setup complete! You can now run 'make pr' to check your changes.${NC}"
+    echo -e "${GREEN}Setup complete! You can now run 'make pr' to check your changes, or 'make docs' to build the docs.${NC}"
+fi
diff --git a/scripts/smoke_test_examples.py b/scripts/smoke_test_examples.py
index 98412dcb3..ea0ffa432 100644
--- a/scripts/smoke_test_examples.py
+++ b/scripts/smoke_test_examples.py
@@ -15,7 +15,7 @@
 
 Run from repo root with the project venv active::
 
-    source venv/bin/activate && python scripts/smoke_test_examples.py
+    . .venv/bin/activate && python scripts/smoke_test_examples.py
 """
 
 from __future__ import annotations