documentation for using using existing virtualenv?

I create my virtualenvs manually and use explicit paths in my projects rather than alter PATH. I have an intense dislike of tools that require an altered environment or otherwise encourage cargo cult behaviour, so I have avoided activate, virtualenvwrapper and such things.

Initially I was turned off by pipenv’s apparent insistence of creating virtualenvs for me and the complete inscrutability of how it does so. The documentation seems to suggest that my only other option was a .venv in my project directory, which I also do not want.

I just now discovered via browsing the issues that pipenv will apparently honour VIRTUAL_ENV. As far as I can tell, this variable is only used by other tools to detect an “activated” virtual env. But virtualenvs don’t need to be “activated” to be used; e.g. python, pip, and other tools work just fine by invoking their full path. I had expected pipenv to behave similarly if installed into the virtualenv.

However, running with VIRTUAL_ENV produces (inconsistently) an annoying “courtesy notice”, and this (and the function name warn_in_virtualenv) leads me to suspect that the scenario is somehow degenerate.

So, what’s the story? Is this feature supported and should it be documented? What is the approprate procedure for managing my dependencies in an existing virtualenv?

If it is intended that pipenv be the recommended tool for managing project dependencies (which is why I am here) then I imagine it appropriate to be far more explicit about how it does things rather than performing magic on the user’s behalf. I also imagine it appropriate for distinct functionality to be less coupled, e.g. lockfile management from virtualenv creation. Considering the lauded zen, one might suspect that python packaging is losing its buddha-nature.

[avdd]

@kennethreitz what, that it is to remain an undocumented feature, with the implication that official python tools are moving towards becoming magical and “opinionated” rather than explicit and thoughtfully engineered?

[kennethreitz]

there’s little action for us to take here – it seems like you have a good understanding of how the tool works.