Things between Poetry, pip and pyproject.toml according to my own reviews.


  • Projects only have pyproject.toml (No
    • Just use pip >= 19.0
  • pip >= 10.0 starts to support PEP 518
  • pip >= 19.0 starts to support PEP 517

Why not anymore?

Accroding to the "Rationale" section of PEP 518:

Using an executable file to specify build requirements under distutils isn't an issue as distutils is part of Python's standard library. Having the build tool as part of Python means that a has no external dependency that a project maintainer needs to worry about to build a distribution of their project. There was no need to specify any dependency information as the only dependency is Python.

But when a project chooses to use setuptools, the use of an executable file like becomes an issue. You can't execute a file without knowing its dependencies, but currently there is no standard way to know what those dependencies are in an automated fashion without executing the file where that information is stored. It's a catch-22 of a file not being runnable without knowing its own contents which can't be known programmatically unless you run the file.

Why pyproject.toml?

  • Say goodbye to lots of requirements.txt files, you just need pyproject.toml
  • Say goodbye to, you just need pyproject.toml
    • No need to write the dependencies in both requirements.txt and
    • Or parsing the requirements.txt in
  • There are some tools start to read their config from pyproject.toml



  • It locks the dependency and generates poetry.lock file just like pipenv
  • The reason why I use poetry instead of pipenv:
    • During my last job, we use pipenv at first.
    • One day, we encountered a strange bug which only showed on the production machine.
    • It turns out the problem is pipenv didn't lock the dependencies properly.
    • We confirmed the bug is made by pipenv.
    • We just give Poetry a try.
    • It fixed the problem.
  • Other reasons why you should consider not using pipenv in 2020 can be found in this blog post: Pipenv: promises a lot, delivers very little | Chris Warrick
  • Poetry is not the first package manager accepts pyproject.toml.
    • I use flit 1.0 back in Apirl, 2018, which supports pyproject.toml
    • And that's the time I know pyproject.toml
    • flit is still being developed and it's lastest version is 2.3.0 now.
    • But, Poetry has more features.


This project is young and still developing. So, like other young projects, lots of things are WIP:

  • During the time I wrote this blog post. It hasn't support the platforms in, but it does have the platforms metadata in the code.
  • Some documentations are not so clear, so you need to search GitHub issues and read lots of discussion to find the answer. And it might be changed in the future.
    • [tool.poetry.scripts] in pyproject.toml works like scripts in setuptools
      • while some people think it's a task runner.
    • [tool.poetry.plugins] in pyproject.toml works like entry_point in setuptools
      • and some people ask "Then why you use the word plugin?"




如果覺得這篇文章對你有幫助, 除了留言讓我知道外, 或許也可以考慮請我喝杯咖啡, 不論金額多寡我都會非常感激且能鼓勵我繼續寫出對你有幫助的文章。

If this blog post happens to be helpful to you, besides of leaving a reply, you may consider buy me a cup of coffee to support me. It would help me write more articles helpful to you in the future and I would really appreciate it.

Related Posts