Merge pull request #3967 from AI-Hypercomputer:shralex_test_7

PiperOrigin-RevId: 919451064

Author: Google-ML-Automation

docs/build_maxtext.md

@@ -42,6 +42,10 @@ gcloud auth configure-docker
 docker run hello-world
 ```
 
+```{note}
+If the `docker run hello-world` command fails with a permission denied error (e.g., `dial unix /var/run/docker.sock: connect: permission denied`), please ensure you have correctly followed step 2 of the prerequisites to configure sudoless Docker. Running `sudo usermod -aG docker $USER` followed by starting a new shell session is usually required to apply the group permissions.
+```
+
 ## Installation Modes
 
 We recommend building MaxText inside a Python virtual environment using `uv` for speed and dependency management.

docs/install_maxtext.md

@@ -149,6 +149,23 @@ environment to avoid dependency conflicts.
      uv pip install -e .[runner] --resolution=lowest
      ```
 
-After installation, you can verify the package is available with
-`python3 -c "import maxtext"` and run training jobs with
-`python3 -m maxtext.trainers.pre_train.train ...`.
+## Verify installation
+
+After installing MaxText (either from PyPI or from source), verify that your virtual environment is healthy and free of package version conflicts:
+
+1. **Verify the environment has no dependency conflicts:**
+
+   ```bash
+   uv pip check
+   ```
+
+   ```{note}
+   If `uv pip check` reports any package version conflicts, they can usually be resolved by starting with a fresh virtual environment (see above) and reinstalling using the platform-specific target and the `--resolution=lowest` flag to ensure all dependencies resolve to their verified versions.
+   ```
+
+2. **Verify MaxText is importable and runnable:**
+
+   ```bash
+   python3 -c "import maxtext"
+   python3 -m maxtext.trainers.pre_train.train --help
+   ```