Request for documention on how to use poetry with multiple python versions

• I have searched the issues of this repo and believe that this is not a duplicate.

Issue

In order to frame my request, let me describe how I anticipate some users come to use poetry (this at least was the case for me):

1. A developer realizes they need a more integrated dependency management solution than just setuptools, and discovers pipenv because it is the top hit on google.
2. They do a bit of reading, and decide that pipenv must be good because it is For Humans™ and it is (or at least was) The Officially Recommended Python Packaging Tool from Python.org. They try it out.
3. The developer inevitably attempts to do something outside the scope of what pipenv is trying to solve and then discover a) that pipenv is really only intended for application developers, and if one is a library developer you still need to use setup.py (making them feel like a second-class citizen), and/or b) the responses to issues filed for pipenv are usually either rude or dismissive.
4. They look for an alternative, and find poetry. There is no rudeness in the issues! The tool actually tries to help all developers! Huzzah!

For people like myself that came to poetry by way of pipenv, the approach to managing virtual environments taken by poetry tripped me up for quite some time because it differs significantly from pipenv.

• In pipenv, one specifies the python version to use for virtual environment creation, and it searches the PATH and creates it for you if a match is found.
• In poetry, it creates the virtual environment from the python against which poetry was installed, or uses a pre-made .venv.

This is a fundamental difference in philosophy between the tools which leads to a fundamental difference in usage on this specific aspect of project/dependency management. Because I had been first exposed to the pipenv way, I (wrongly) assumed that poetry also worked this way and struggled to get poetry to use a python 3.5 virtual environment because I had installed poetry against python 3.6; this was especially confusing because I had set the python version in the pyproject.toml to 3.5. I did notice the Poetry and virtualenvs section, but for someone who has not yet grokked the design philosophy of poetry there is not enough information for someone used to what pipenv does to adapt to poetry’s approach.

REQUEST (finally)

I think the documentation for poetry would be improved if one (or both) of the following were added to documentation:

• A section on the correct way to use poetry with multiple python versions (along with a discussion on the philosophy behind this design decision). Perhaps formalizing the discussion that occurred in https://github.com/sdispater/poetry/pull/82? It would be useful if it address both using pyenv and also using a pre-existing .venv. This could just mean expanding the Poetry and virtualenvs section.
• A section on how to migrate to poetry from pipenv. Here, the differences in philosophy could be specifically addressed and spelled out so that new users do not get frustrated at the first step.

It would also be helpful if this information were in the README itself, or at least linked to in the README.

[festinuz]

After spending some time reading other issues where its mentioned (#9 #35 #57 #77 #82), here’s a summary: A lot of people get confused about what poetry does and what it doesnt do in regard to virtualenv.

It actually is kind of an edge case where it always tries to create virtualenv and work inside of it, but it doesnt provide any support for different virtualenvs and such.

Here are my thoughts on this. Poetry can either:

1. Extend support of virtualenvs to the point that user could use poetry as an abstraction above virtualenvs (which i would love);
2. Drop support of virtualenvs altogether in favor of user using external tools such as pew/pyenv/virtualenv to manage virtualenvs by himself;
3. Clarify documentation in regards to how poetry manages virtualenvs.

Regardles of whatever gets chosen as a solution, we should really update the documentation as it is a common point of confusion among new users (myself included).

[laike9m]

I think Poetry should just use whatever environment it’s in, and not creating a virtualenv.