@@ -4,7 +4,7 @@ This file provides guidance to AI coding agents when working with code in this r
 
 ## Commands
 
-All `make` targets use (and create if needed) the virtualenv in `.venv` from `requirements.txt`.
+All `make` targets use (and create if needed, via `python3 -m venv`) the virtual environment in `.venv` from `requirements.txt`.
 
 - `make depend` — set up venv and download the ObjectBox C shared libraries (`download-c-lib.py`) into `objectbox_clib/lib/<arch>/`. Required once after checkout and whenever the C library version changes.
 - `make depend-sync` — download the Sync variant of the C libraries into `objectbox_sync_clib/lib/<arch>/`; if present, it is loaded instead (needed for the Sync tests).
 
@@ -29,7 +29,8 @@ platform) which actually implements the database functionality. The library shou
 #### Initial setup
 If you're just getting started, run the following simple steps to set up the repository on your machine
 * clone this repository
-* `make depend` to initialize `virtualenv` and get dependencies (objectbox-c shared library)
+* `make depend` to create a virtual environment (`.venv`) and get dependencies (objectbox-c shared library);
+  on Debian/Ubuntu, this requires the `python3-venv` package
 * `make` to build and test
 
 You can also run `make help` to see all available options.
 
@@ -40,8 +40,8 @@ build-sync: ${VENV}		## Build objectbox-sync-clib wheels and the objectbox-sync
 ${VENV}: ${VENVBIN}/activate
 
 venv-init:
-	${PIP} install --user virtualenv
-	${PYTHON} -m virtualenv ${VENV}
+	@# venv is part of Python; pip/setuptools/wheel come from requirements.txt (e.g. venv has no setuptools since 3.12)
+	${PYTHON} -m venv ${VENV} || { echo "Creating ${VENV} failed; on Debian/Ubuntu, install python3-venv" ; exit 1 ; }
 
 # 	remove packages not in the requirements.txt
 # 	install and upgrade based on the requirements.txt