From 98346dd137b3a464edff98e24227015e7ca3fcee Mon Sep 17 00:00:00 2001
From: David Hewitt <1939362+davidhewitt@users.noreply.github.com>
Date: Wed, 25 Oct 2023 23:27:12 +0100
Subject: [PATCH] docs: improve detail around pyenv install

---
 guide/src/getting_started.md | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/guide/src/getting_started.md b/guide/src/getting_started.md
index 682632cf..e3f27771 100644
--- a/guide/src/getting_started.md
+++ b/guide/src/getting_started.md
@@ -14,13 +14,21 @@ To use PyO3, you need at least Python 3.7. While you can simply use the default
 
 ## Virtualenvs
 
-While you can use any virtualenv manager you like, we recommend the use of `pyenv` in particular if you want to develop or test for multiple different Python versions, so that is what the examples in this book will use. The installation instructions for `pyenv` can be found [here](https://github.com/pyenv/pyenv#getting-pyenv).
+While you can use any virtualenv manager you like, we recommend the use of `pyenv` in particular if you want to develop or test for multiple different Python versions, so that is what the examples in this book will use. The installation instructions for `pyenv` can be found [here](https://github.com/pyenv/pyenv#getting-pyenv). You will need to install both `pyenv` and the [`pyenv-virtualenv`](https://github.com/pyenv/pyenv-virtualenv) plugin. The [pyenv installer](https://github.com/pyenv/pyenv-installer#installation--update--uninstallation) will install both together.
 
-Note that when using `pyenv`, you should also set the following environment variable:
+If you intend to run Python from Rust (for example in unit tests) you should set the following environment variable when installing a new Python version using `pyenv`:
 ```bash
 PYTHON_CONFIGURE_OPTS="--enable-shared"
 ```
 
+For example:
+
+```bash
+env PYTHON_CONFIGURE_OPTS="--enable-shared" pyenv install 3.12
+```
+
+You can read more about `pyenv`'s configuration options [here](https://github.com/pyenv/pyenv/blob/master/plugins/python-build/README.md#building-with---enable-shared).
+
 ### Building
 
 There are a number of build and Python package management systems such as [`setuptools-rust`](https://github.com/PyO3/setuptools-rust) or [manually](https://pyo3.rs/latest/building_and_distribution.html#manual-builds). We recommend the use of `maturin`, which you can install [here](https://maturin.rs/installation.html). It is developed to work with PyO3 and provides the most "batteries included" experience, especially if you are aiming to publish to PyPI. `maturin` is just a Python package, so you can add it in the same you already install Python packages.