Check environment variable PIPENV_CUSTOM_VENV_NAME

docs/advanced.rst

@@ -558,6 +558,19 @@ wherever you want, e.g.::
 
 In addition, you can also have Pipenv stick the virtualenv in ``project/.venv`` by setting the ``PIPENV_VENV_IN_PROJECT`` environment variable.
 
+☤ Virtual Environment Name
+-------------------------------------
+
+The virtualenv name created by Pipenv may be different from what you were expecting.
+Dangerous characters (i.e. ``$`!*@"`` as well as space, line feed, carriage return,
+and tab) are converted to underscores. Additionally, the full path to the current
+folder is encoded into a "slug value" and appended to ensure the virtualenv name
+is unique.
+
+Pipenv supports a arbitrary custom name for the virtual environment set at ``PIPENV_CUSTOM_VENV_NAME``.
+
+The logical place to specify this would be in a user's ``.env`` file in the root of the project, which gets loaded by pipenv when it is invoked.
+
 
 ☤ Testing Projects
 ------------------

docs/basics.rst

@@ -313,12 +313,6 @@ The user can provide these additional parameters:
                  **destructive** and will delete your current virtualenv before replacing
                  it with an appropriately versioned one.
 
-    .. note:: The virtualenv created by Pipenv may be different from what you were expecting.
-              Dangerous characters (i.e. ``$`!*@"`` as well as space, line feed, carriage return,
-              and tab) are converted to underscores. Additionally, the full path to the current
-              folder is encoded into a "slug value" and appended to ensure the virtualenv name
-              is unique.
-
     - ``--dev`` — Install both ``develop`` and ``default`` packages from ``Pipfile``.
     - ``--system`` — Use the system ``pip`` command rather than the one from your virtualenv.
     - ``--deploy`` — Make sure the packages are properly locked in Pipfile.lock, and abort if the lock file is out-of-date.

news/4974.feature.rst

@@ -0,0 +1 @@
+support PIPENV_CUSTOM_VENV_NAME to be the venv name if specified, update relevant docs.

pipenv/environments.py

@@ -335,6 +335,9 @@ def initialize(self):
         approach, you may set this to '0', 'off', or 'false'.
         """
 
+        self.PIPENV_CUSTOM_VENV_NAME = os.getenv("PIPENV_CUSTOM_VENV_NAME", None)
+        """Tells Pipenv whether to name the venv something other than the default dir name."""
+
         self.PIPENV_PYUP_API_KEY = os.environ.get("PIPENV_PYUP_API_KEY", None)
 
         # Internal, support running in a different Python from sys.executable.

pipenv/project.py

@@ -365,6 +365,9 @@ def get_name(name, location):
 
     @property
     def virtualenv_name(self) -> str:
+        custom_name = self.s.PIPENV_CUSTOM_VENV_NAME
+        if custom_name:
+            return custom_name
         sanitized, encoded_hash = self._get_virtualenv_hash(self.name)
         suffix = ""
         if self.s.PIPENV_PYTHON:

tests/integration/test_dot_venv.py

@@ -161,3 +161,19 @@ def test_venv_in_project_default_when_venv_exists(PipenvInstance):
 
             assert venv_loc.joinpath('.project').exists()
             assert venv_loc == Path(venv_path)
+
+
+@pytest.mark.dotenv
+def test_venv_name_accepts_custom_name_environment_variable(PipenvInstance):
+    """Tests that virtualenv reads PIPENV_CUSTOM_VENV_NAME and accepts it as a name
+    """
+    with PipenvInstance(chdir=True, venv_in_project=False) as p:
+        test_name = "sensible_custom_venv_name"
+        with temp_environ():
+            os.environ['PIPENV_CUSTOM_VENV_NAME'] = test_name
+            c = p.pipenv('install')
+            assert c.returncode == 0
+            c = p.pipenv('--venv')
+            assert c.returncode == 0
+            venv_path = c.stdout.strip()
+            assert test_name == Path(venv_path).parts[-1]