Python: Setting up the environment
2026-02-21 02:53 Diff
https://hexlet.io/courses/python-setup-environment/lessons/start-with-poetry/theory_unit

In all projects in the Python profession, we suggest using the poetry tool. It can help you can manage dependencies. It is one of the most essential tools used by Python developers today.

Poetry is a simple and handy tool that makes it easy to maintain and develop projects. We advise you to design each learning experiment as a poetry project so that you get used to professional tools faster.

In this lesson, we'll look at how to work with Poetry. We'll go through the following steps:

  • Installation
  • Setting up
  • Creating your first poetry project
  • Working with pyproject.toml
  • Initializing a virtual environment

How to install Poetry

Poetry creators wrote it in Python, but it's not the usual Python program you install using pip install. In the introductory section of the Poetry documentation you'll find commands to install the program on your operating system.

When you install Poetry, it'll be available as a separate command in the shell:

That's all about installing the program. Before we create our first project, let's set up the tool to make it more convenient for us to work.

How to customize Poetry

If you ask for a list of Poetry settings immediately after installation, you'll see the following:

Poetry works with virtual environments. And it's initially set up in a way that means you'll have many different versions of Python. For this reason, the tool creates virtual environments for projects in an unusual location - note the virtualenvs.path setting.

You can use the default settings, but Python developers usually store the virtual environment for each project in the project directory, specifically in the .venv subdirectory.

Remember how you created environments with the python3 -m venv .venv command. In Poetry, you should do the same:

Now every poetry project will have a virtual environment. For example, you can transfer a project from one machine to another by copying the directory.

Once we set up Poetry, it'll be ready for us to create our first project.

How to create your first project

Create a poetry project with the command poetry new NAME. Before running Poetry, check if the python3 command is available in the system.

Suppose you entered the poetry new first command first. It is what the result will look like:

The message Created package first in first package first in first means that a package called first was created in a directory called first with a corresponding __init__.py. Any Poetry project will always contain at least one package. In addition to the first package, the project already has a tests package. We don't need it yet, but it's worth knowing that real projects always have a test package.

You'll also have a README.md file in the actual project, which should contain the project description. This file has the .md — extension, which means it's a Markdown file. It is a popular markup format. By the way, we wrote this lesson in it.

The most important file in the poetry project is pyproject.toml. It is the file format TOML. You can read more about it here. The pyproject.toml file contains the project configuration. The information from this file is needed so that Poetry can:

  • Manage project dependencies
  • Run code for execution
  • Run development tools
  • Build a distribution and publish it on PyPI

The more you work with Poetry, the better you are at publishing projects. You'll gradually get used to the fact that every package must have a description, a proper structure, and a specified version. We advise you to design projects according to these standards, even if you don't intend to publish the project in the index.

We've created our first project. Now we need to deal with pyproject.toml.

How to work with pyproject.toml

The configuration file for a new project looks something like this:

Lines like [tool.poetry] describe sections with key = value pairs.

We cannot place most keys in other sections. You can study the keys in more detail and find out where they belong in the documentation. Here we'll look at lines like these:

  • tool.poetry — describes the project from Poetry's perspective, where we store the version, description, and the name of the project
  • tool.poetry.dependencies — stores a list of dependencies required for the code to work. Python itself will always be listed here. We can't run the code without it

The build-system section indicates that we have a project managed by Poetry. That said, there are other tools to manage projects. The build-system section looks different for them. All that's left is to deal with the last step - the initialization of the virtual environment.

How to initialize a virtual environment

Poetry realizes that it's time to create or update the environment. In this case, you can call poetry install:

This command installs all dependencies in the environment in the .venv directory inside the project.

The environment is activated with the command poetry shell and terminated with exit:

It's often not necessary to activate the environment. Poetry offers a run command which executes programs from within the environment. For example, it's customary within the project to launch the REPL with the poetry run python command.

It is what working with Poetry looks like. It is a handy tool, so we recommend using it. Make your experiments look like Poetry projects. It will help you learn how to use Poetry faster.

Conclusions

  • Poetry is a handy tool that simplifies project development and maintenance
  • Poetry isn't installed via pip install, we use special commands found in the Poetry documentation to install it
  • Every project needs to have a virtual environment. Poetry needs to be pre-configured for this
  • Each package must have a description and the correct structure and version assigned