MarcusSaviour
diff --git a/‎README.md
Lines changed: 31 additions & 5 deletions b/‎README.md
Lines changed: 31 additions & 5 deletions
@@ -136,14 +136,40 @@ You should specify only a major and minor version if you are okay with the most
 
 # Using `setup-python` with a self hosted runner
 
-If you would like to use `setup-python` and a self-hosted runner, there isn't much that you need to do. When `setup-python` is run for the first time with a version of Python that it doesn't have, it will download the appropriate version, and set up the tools cache on your machine. Any subsequent runs will use the Python versions that were previously downloaded.
+If you would like to use `setup-python` and a self-hosted runner, there are a few extra things you need to make sure are set up so that new versions of Python can be downloaded and configured on your runner.
 
-A few things to look out for when `setup-python` is first setting up the tools cache
-- If using Windows, your runner needs to be running as an administrator so that the appropriate directories and files can be setup. On Linux and Mac, you also need to be running with elevated permissions
-- On Windows, you need `7zip` installed and added to your `PATH` so that files can be extracted properly during setup
-- MSI installers are used when setting up Python on Windows. A word of caution as MSI installers update registry settings
+### Windows
+
+- Your runner needs to be running with administrator privileges so that the appropriate directories and files can be set up when downloading and installing a new version of Python for the first time.
+- If your runner is configured as a service, make sure the account that is running the service has the appropriate write permissions so that Python can get installed. The default `NT AUTHORITY\NETWORK SERVICE` should be sufficient. 
+- You need `7zip` installed and added to your `PATH` so that the downloaded versions of Python files can be extracted properly during first-time setup.
+- MSI installers are used when setting up Python on Windows. A word of caution as MSI installers update registry settings.
 - The 3.8 MSI installer for Windows will not let you install another 3.8 version of Python. If `setup-python` fails for a 3.8 version of Python, make sure any previously installed versions are removed by going to "Apps & Features" in the Settings app.
 
+### Linux
+
+- The Python packages that are downloaded from `actions/python-versions` are originally compiled from source in `/opt/hostedtoolcache/` with the [--enable-shared](https://github.com/actions/python-versions/blob/94f04ae6806c6633c82db94c6406a16e17decd5c/builders/ubuntu-python-builder.psm1#L35) flag, which makes them non-relocatable.
+- Create an environment variable called `AGENT_TOOLSDIRECTORY` and set it to `/opt/hostedtoolcache`. This controls where the runner downloads and installs tools.
+  - In the same shell that your runner is using, type `export AGENT_TOOLSDIRECTORY=/opt/hostedtoolcache`
+  - A more permanent way of setting the environment variable is to create a `.env` file in the same directory as your runner and to add `AGENT_TOOLSDIRECTORY=/opt/hostedtoolcache`. This ensures the variable is always set if your runner is configured as a service.
+- Create a directory called `hostedtoolcache` inside `/opt`.
+- The user starting the runner must have write permission to the `/opt/hostedtoolcache` directory. It is not possible to start the Linux runner with `sudo` and the `/opt` directory usually requires root privileges to write to. Check the current user and group that the runner belongs to by typing `ls -l` inside the runners root directory.
+- The runner can be granted write access to the `/opt/hostedtoolcache` directory using a few techniques:
+  - The user starting the runner is the owner, and the owner has write permission
+  - The user starting the runner is in the owning group, and the owning group has write permission
+  - All users have write permission 
+    - `sudo chown runner-user:runner-group opt/hostedtoolcache/`
+- If your runner is configured as a service and you run into problems, make sure the user that the service is running as is correct. For more information, you can [check the status of your self-hosted runner](https://help.github.com/en/actions/hosting-your-own-runners/configuring-the-self-hosted-runner-application-as-a-service#checking-the-status-of-the-service).
+
+### Mac
+
+- The same setup that applies to `Linux` also applies to `Mac`, just with a different tools cache directory.
+- Create a directory called `/Users/runner/hostedtoolcache`
+- Set the `AGENT_TOOLSDIRECTORY` environment variable to `/Users/runner/hostedtoolcache`.
+- Change the permissions of `/Users/runner/hostedtoolcache` so that the runner has write access.
+
+
 # Using Python without `setup-python`
 
 `setup-python` helps keep your dependencies explicit and ensures consistent behavior between different runners. If you use `python` in a shell on a GitHub hosted runner without `setup-python` it will default to whatever is in PATH. The default version of Python in PATH vary between runners and can change unexpectedly so we recommend you always use `setup-python`.