diff --git a/README.md b/README.md
index 08f410fe07..f2a6aa23c3 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,12 @@ _For comparison to other tools including pipsi, see [Comparison to Other Tools](
## Install pipx
+> [!NOTE]
+> It is not recommended to install `pipx` via `pipx`. If you'd like
+> to do this anyway, take a look at the
+> [`pipx-in-pipx`](https://github.com/mattsb42-meta/pipx-in-pipx) project and
+> read about the limitations there.
+
### On macOS
```
@@ -69,7 +75,7 @@ Restart your terminal session and verify `pipx` does run.
Upgrade pipx with `py -m pip install --user --upgrade pipx`.
-### Via zipapp
+### Using pipx without installing (via zipapp)
You can also use pipx without installing it.
The zipapp can be downloaded from [Github releases](https://github.com/pypa/pipx/releases) and you can invoke it with a Python 3.7+ interpreter:
diff --git a/docs/installation.md b/docs/installation.md
index e8da2573bc..d559104955 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -6,7 +6,7 @@ You also need to have `pip` installed on your machine for `python3`. Installing
pipx works on macOS, linux, and Windows.
-## Install pipx
+## Installing pipx
On macOS:
@@ -29,18 +29,24 @@ python3 -m pip install --user pipx
python3 -m pipx ensurepath
```
-Or via zipapp:
+!!!caution
+ It is not recommended to install `pipx` via `pipx`. If you'd like
+ to do this anyway, take a look at the
+ [`pipx-in-pipx`](https://github.com/mattsb42-meta/pipx-in-pipx) project and
+ read about the limitations there.
-You can also use pipx without installing it.
+
+### Using pipx without installing (via zipapp)
The zipapp can be downloaded from [Github releases](https://github.com/pypa/pipx/releases) and you can invoke it with a Python 3.7+ interpreter:
```
python pipx.pyz ensurepath
```
-Or use with pre-commit:
+### Using pipx with pre-commit
Pipx has [pre-commit](https://pre-commit.com/) support. This lets you run applications:
+
* That can be run using `pipx run` but don't have native pre-commit support.
* Using its prebuilt wheel from pypi.org instead of building it from source.
* Using pipx's `--spec` and `--index-url` flags.
@@ -58,7 +64,7 @@ Example configuration for use of the code linter [yapf](https://github.com/googl
types: ['python']
```
-### Installation Options
+## Installation Options
The default binary location for pipx-installed apps is `~/.local/bin`. This can be overridden with the environment variable `PIPX_BIN_DIR`.