Skip to content

Commit 1e2b0bc

Browse files
authored
Docs: Recommend pipx for PEP 668 compatibility (#90)
1 parent c8f8d71 commit 1e2b0bc

1 file changed

Lines changed: 43 additions & 2 deletions

File tree

README.md

Lines changed: 43 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ This package provides `tflocal` - a small wrapper script to run [Terraform](http
77
## Prerequisites
88

99
* Python 3.x
10-
* `pip`
10+
* `pip` or `pipx`
1111
* `terraform`
1212

1313
## How it works
@@ -16,11 +16,52 @@ The script uses the [Terraform Override mechanism](https://www.terraform.io/lang
1616

1717
## Installation
1818

19-
The `tflocal` command line interface can be installed via `pip`:
19+
The recommended way to install tflocal is using pipx, which installs Python CLI tools in their own isolated environments. This avoids conflicts with system packages and the externally-managed-environment error (PEP 668) seen on modern Linux distributions.
20+
21+
##### 1) Recommended: Using pipx
22+
23+
24+
First, ensure pipx is installed.
25+
26+
On Debian/Ubuntu:
27+
28+
```
29+
sudo apt install pipx
30+
```
31+
Or, using pip (for other systems):
32+
33+
```
34+
pip install --user pipx
35+
```
36+
Then, run pipx ensurepath to add pipx's binaries to your system's PATH. You may need to restart your shell for this to take effect.
37+
38+
#### Install tflocal with pipx:
39+
Bash
40+
41+
pipx install terraform-local
42+
43+
To upgrade tflocal in the future, run: pipx upgrade terraform-local.
44+
45+
##### 2) Alternative: Using a Virtual Environment
46+
47+
If you prefer not to use pipx, you can install tflocal into a standard Python virtual environment (venv):
48+
Bash
49+
50+
# Create a virtual environment (e.g., in your project directory)
51+
```
52+
python3 -m venv .venv
53+
```
54+
# Activate it
55+
```
56+
source .venv/bin/activate
57+
```
58+
# Install the package
2059
```
2160
pip install terraform-local
2261
```
2362

63+
# Note: You must activate this venv (source .venv/bin/activate) every time you want to use the tflocal command.
64+
2465
## Configurations
2566

2667
The following environment variables can be configured:

0 commit comments

Comments
 (0)