Beginner Guide on “Poetry”, New Python dependency management tool
Tags: python, poetry, pipenv, package
Published: 2019-04-20 09:33:04

---
title: Beginner Guide on “Poetry”, New Python dependency management tool
published: true
description: Introduction to using "Poetry", Python dependency management tool
tags: python, poetry, pipenv, package
---

# Why I write this post?
Once I wrote a [blog post](https://dev.to/yukinagae/your-first-guide-to-getting-started-with-pipenv-50bn) about “pipenv”, which is one of the Python package management tools,  [Dylan](https://dev.to/dbanty) gave me a [comment](https://dev.to/dbanty/comment/a6h9)  on the post.

He pointed out some of the issues on pipenv, and his suggestion was to use [Poetry](https://poetry.eustace.io) instead of pipenv.

In this post, I’ll briefly cover what Poetry is and some usage of it. This is just a first try to use Poetry, and hopefully, I write more details in the future blog posts :)


# What is “Poetry” and why?
*Poetry* is a Python dependency management tool.

The main reason why Poetry developed is mentioned [here](https://github.com/sdispater/poetry#why).

> Packaging systems and dependency management in Python are rather convoluted and hard to understand for newcomers. Even for seasoned developers it might be cumbersome at times to create all files needed in a Python project:setup.py, requirements.txt, setup.cfg, MANIFEST.in and the newly added Pipfile.

This is really true that there are many files we should consider such as:

* setup.py
* requirements.txt
* setup.cfg
* MANIFEST.in
* Pipfile and Pipfile.lock (pipenv)

To solve this messy situation, Poetry comes here for us with only one `pyproject.toml` file to manage all the dependencies.

Now, let’s setup Poetry!

# Setup Poetry

## Requirements
* Python 2.7 or 3.4+

I’ll use Python 3.6.0 in this post.

```bash
$ python --version
Python 3.6.0
```

## Installation

Install Poetry via an installer provided.

```bash
$ curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python
Retrieving Poetry metadata

# Welcome to Poetry!

This will download and install the latest version of Poetry,
a dependency and package manager for Python.

It will add the `poetry` command to Poetry's bin directory, located at:

$HOME/.poetry/bin

This path will then be added to your `PATH` environment variable by
modifying the profile files located at:

$HOME/.profile
$HOME/.bash_profile

You can uninstall at any time with `poetry self:uninstall`,
or by executing this script with the --uninstall option,
and these changes will be reverted.

Installing version: 0.12.12
  - Downloading poetry-0.12.12-darwin.tar.gz (7.23MB)

Poetry (0.12.12) is installed now. Great!

To get started you need Poetry's bin directory ($HOME/.poetry/bin) in your `PATH`
environment variable. Next time you log in this will be done
automatically.

To configure your current shell run `source $HOME/.poetry/env`
```


To activate `poetry` command, run the following command:

```bash
source $HOME/.poetry/env
```

Now, `poetry` command should be available. Let’s check the Poetry version installed.
 
```bash
$ poetry —version
Poetry 0.12.12
```

It works!

# Poetry demo
## Create a template

First, I’ll create a demo app.

```bash
poetry new poetry-demo
```

The project structure is like this.

```bash
$ cd poetry-demo
$ tree
.
├── README.rst
├── poetry_demo
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_poetry_demo.py
```

Let’s see `pyproject.toml`.

```toml
[tool.poetry]
name = "poetry-demo"
version = "0.1.0"
description = ""
authors = ["[Your Name] <[Your Email]>"]

[tool.poetry.dependencies]
python = "^3.6"

[tool.poetry.dev-dependencies]
pytest = "^3.0"

[build-system]
requires = ["poetry>=0.12"]
build-backend = "poetry.masonry.api"
```

## Add dependency
I can specify a dependency in the `pyproject.toml` file directly, but it looks easy for me to use `add` command.

```bash
poetry add pendulum
```

Automatically, `pendulum` is added to the `pyproject.toml` file.

```toml
[tool.poetry.dependencies]
python = "^3.6"
pendulum = "^2.0"
```

Also, `poetry.lock` is created.

```bash
$ tree
.
├── README.rst
├── poetry.lock
├── poetry_demo
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_poetry_demo.py
```

Since this is just a first try to use Poetry, I’ll continue using it and may write a blog post again if I find something useful :)

# TODO
There are several things I’d like to try:

- [ ] How to integrate with existing requirements.txt?
- [ ] Try Poetry `publish` command to publish my package to PyPI
- [ ] Compare Poetry with pipenv


# References
* Poetry
	* [Poetry - Python dependency management and packaging made easy.](https://poetry.eustace.io): Official documentation
	* [sdispater/poetry: Python dependency management and packaging made easy.](https://github.com/sdispater/poetry): GitHub
* [Python Application Dependency Management in 2018 · Homepage of Hynek Schlawack](https://hynek.me/articles/python-app-deps-2018/)