Getting Started with Python Poetry


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.

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

  • 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 -UseBasicParsing).Content | python -

Installing Poetry on OSX/Unix

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

curl -sSL | python
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.

poetry new poetry-project
├── poetry_project
│ └──
├── pyproject.toml
└── tests
└── test_poetry_project
name = "poetry-project"
version = "0.1.0"
description = ""
authors = ["Favour Kelvin <>"]
python = "^3.8"
pytest = "^5.2"
requires = ["poetry>=1.0.0"]
build-backend = "poetry.masonry.api"
  • 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.
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.

Software engineer, Technical writer. I enjoy the synergy of writing and technology