From 5a5d238f87f9fe2e0e7bf87d0e35c978561c3ab0 Mon Sep 17 00:00:00 2001
From: frostming <frostming@tencent.com>
Date: Fri, 28 Aug 2020 16:45:56 +0800
Subject: [PATCH 1/2] Discourage homebrew installation in doc

---
 README.md        | 12 ++++--------
 docs/install.rst | 40 ++++++++++++++++++++++++++++------------
 2 files changed, 32 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 21b5b3b3ef..9b7ff6d0d0 100644
--- a/README.md
+++ b/README.md
@@ -41,25 +41,21 @@ You can quickly play with Pipenv right in your browser:
 Installation
 ------------
 
-If you\'re on MacOS, you can install Pipenv easily with Homebrew:
-
-    $ brew install pipenv
-
-Or, if you\'re using Debian Buster+:
+If you\'re using Debian Buster+:
 
     $ sudo apt install pipenv
 
 Or, if you\'re using Fedora:
 
     $ sudo dnf install pipenv
-    
+
 Or, if you\'re using FreeBSD:
 
     # pkg install py36-pipenv
 
-When none of the above is an option:
+When none of the above is an option, it is recommended to use [Pipx](https://pypi.org/p/pipx):
 
-    $ pip install pipenv
+    $ pipx install pipenv
 
 Otherwise, refer to the [documentation](https://pipenv.pypa.io/en/latest/#install-pipenv-today) for instructions.
 
diff --git a/docs/install.rst b/docs/install.rst
index 97e756981c..364d0c55d8 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -80,22 +80,17 @@ cases.
 .. _bundler: http://bundler.io/
 
 
-☤ Homebrew Installation of Pipenv
----------------------------------
+☤ Isolated Installation of Pipenv with Pipx
+-------------------------------------------
 
-`Homebrew`_ is a popular open-source package management system for macOS. For Linux users, `Linuxbrew`_  is a Linux port of that.
+`Pipx`_ is a tool to help you install and run end-user applications written in Python. It installs applications
+into an isolated and clean environment on their own. To install pipx, just run::
 
-Installing pipenv via Homebrew or Linuxbrew will keep pipenv and all of its dependencies in
-an isolated virtual environment so it doesn't interfere with the rest of your
-Python installation.
+    $ pip install --user pipx
 
-Once you have installed Homebrew or Linuxbrew simply run::
+Once you have ``pipx`` ready on your system, continue to install Pipenv::
 
-    $ brew install pipenv
-
-To upgrade pipenv at any time::
-
-    $ brew upgrade pipenv
+    $ pipx install pipenv
 
 
 ☤ Pragmatic Installation of Pipenv
@@ -149,6 +144,27 @@ If you don't even have pip installed, you can use this crude installation method
     $ curl https://raw.githubusercontent.com/pypa/pipenv/master/get-pipenv.py | python
 
 
+☤ Homebrew Installation of Pipenv(Discouraged)
+----------------------------------------------
+`Homebrew`_ is a popular open-source package management system for macOS. For Linux users, `Linuxbrew`_  is a Linux port of that.
+
+Installing pipenv via Homebrew or Linuxbrew will keep pipenv and all of its dependencies in
+an isolated virtual environment so it doesn't interfere with the rest of your
+Python installation.
+
+Once you have installed Homebrew or Linuxbrew simply run::
+
+    $ brew install pipenv
+
+To upgrade pipenv at any time::
+
+    $ brew upgrade pipenv
+
+.. Note::
+    Homebrew installation is discouraged because each time the Homebrew Python is upgraded, which Pipenv depends on,
+    users have to re-install Pipenv, and perhaps all virtual environments managed by it.
+
+
 ☤ Installing packages for your project
 ======================================
 

From edeaffba9486ddf379aa65ab983a94f6bfcf0d59 Mon Sep 17 00:00:00 2001
From: frostming <frostming@tencent.com>
Date: Fri, 28 Aug 2020 16:48:52 +0800
Subject: [PATCH 2/2] add news fragment

---
 news/4013.doc.rst | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 news/4013.doc.rst

diff --git a/news/4013.doc.rst b/news/4013.doc.rst
new file mode 100644
index 0000000000..8b5353e5b9
--- /dev/null
+++ b/news/4013.doc.rst
@@ -0,0 +1 @@
+Discourage homebrew installation in installation guides.