Getting Started with Python Poetry

4 min readMay 20, 2021

Introduction

Python has different options when it comes to virtual environment. Virtualenv, Pipenv, Conda, and Poetry all strive to maintain Python libraries project-specific, and they all succeed admirably.

Both Pip and Virtualenv were added to Python during the years when dependencies were installed manually into a device folder. At the moment, the idea of isolating packages on a per-project basis was quite new.

Poetry is perhaps the most advanced dependency management option accessible in Python today. Poetry extends far past dependencies, with functionality such as generating. lock files, scaffolding projects, and a ton of configuration choices, many of which are managed with a simple CLI.

It is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.]

Use Cases

Poetry simplifies and automates the method of managing a Python project via its CLI and a single configuration file. With poetry, you can

Create, manage and package python project
Manage virtual environments for the project.
Publish and build packages at ease.
Install and manage dependencies and versions for your project

Getting Started

To get started with installing poetry I assume we have python 3 installed. Having the right version of python makes it easy to install Poetry.

Installing Poetry on Windows

To install Poetry on Windows, open a PowerShell window and then copy and paste this:

(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python -

Make sure %USERPROFILE%\.poetry\bin is your PATH variable. You can edit this by searching your Start menu for environment and edit the environment variables for your account.

Installing Poetry on OSX/Unix

To install Poetry on Linux and Mac etc, copy and paste the following command on your terminal.

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python

Make sure $HOME/.poetry/bin is in your PATH variable. In most cases, Poetry will modify your ~/.profile to source $HOME/.poetry/env. Nevertheless, you can always configure your PATH the way you want.

Note: To confirm if your poetry was installed, run the following command

poetry --version

Using Poetry

Creating a new project

Let’s create a new project using poetry. Poetry has a CLI you can run on your terminal, which allows us to create and configure Python projects easily.

To get started copy and paste the following command on your terminal.

poetry new poetry-project

This generates a standard Python folder structure for our new project named poetry-project very easy. The structure of a project created with Poetry looks like this:

/poetry-project
├── README.md
├── poetry_project
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_poetry_project

The most important file here is pyproject.toml which holds all the information necessary to manage our package.

This is where we define everything from our project’s metadata, dependencies, scripts, and more. This is what the pyproject.toml looks like

[tool.poetry]
name = "poetry-project"
version = "0.1.0"
description = ""
authors = ["Favour Kelvin <youremail@example.com>"][tool.poetry.dependencies]
python = "^3.8"[tool.poetry.dev-dependencies]
pytest = "^5.2"[build-system]
requires = ["poetry>=1.0.0"]
build-backend = "poetry.masonry.api"

Here we have four sections defined:

The first section defines all metadata not related to dependency packages like name, version, etc.
The second section defines all the dependencies needed for the project.
The third section defines all development dependencies not necessary to build the project but to perfom other actions like testing, building, documentation, etc. Dev dependencies are packages that contributing developers should download to iterate on this project.
The fourth section defines a build system. This is section is usually not touched unless you upgrade your version of Poetry.

If you don’t like that poetry initializes a project for you or if you already have a project that you want to control with poetry, you can use the init command. You will get an interactive shell to configure your project.

cd pre-existing-project
poetry init

Poetry CLI

Poetry’s command-line interface is very simple to use. It has features that enable you to manage various configurations for your packages. With Poetry CLI you can:

Installing & Managing Dependencies

poetry shell: creates a Python virtual environment that will be associated with your project.
poetry install: Installs the dependencies specified in pyproject.toml
poetry update: Update dependencies to newer versions.
poetry add [package-name: Adds a dependency to pyproject.toml.
poetry remove [package-name]: Removes a dependency from pyproject.toml
poetry export -f requirements.txt > requirements.txt: Exports the contents of your project’s .lock file to requirements.txt.

Configure your packages

poetry config: shows the paths of the current virtual environment or environment variables.
poetry show: shows packages currently installed to the project, including dev-dependency.
poetry check: Checks for errors in pyproject.toml.

Executing Applications

poetry run [script-name]: Executes a script specified in [tool.poetry.scripts] section of pyproject.toml.

Building and Publishing

poetry build: Builds a package.
poetry publish: Publishes the output of the build to the project’s external repository PyPi.