If you’ve worked with Python, you’ve probably used pip to install packages. It’s the default tool in Python to add libraries like Flask, Requests, or Pandas.
But there's another tool called Poetry that does more than just install packages. Poetry helps manage your whole Python project: dependencies, virtual environments, versioning, and publishing, all in one place.
In this article, we’ll explain:
What Poetry is
How to install and use it
How it compares with pip
When to choose Poetry over pip
Let’s begin!
📦 What Is Poetry?
Poetry is a Python dependency and package manager. It was created to solve the common problems Python developers face, such as:
Messy requirements.txt files
Confusing virtual environments
Publishing packages to PyPI manually
Poetry uses a single file — pyproject.toml — to manage your dependencies and project configuration.
It also creates and manages a virtual environment automatically, so you don't have to use tools like venv or virtualenv.
🔧 Installing Poetry
To install Poetry, you can run this one-line command in your terminal:
curl -sSL https://install.python-poetry.org | python3 -
After installation, make sure it works:
poetry --version
If that prints something like Poetry (version 2.1.3), you’re good to go!
🚀 How to Use Poetry
1. Create a New Project
poetry new my_project
This creates a folder my_project with this structure:
my_project/
├── pyproject.toml
├── README.rst
├── my_project/
│ └── __init__.py
└── tests/
└── test_my_project.py
2. Add a Dependency
poetry add requests
Poetry:
Adds requests to the pyproject.toml
Installs it in a virtual environment
Creates or updates the poetry.lock file
3. Activate the Virtual Environment
Poetry creates a virtual environment automatically.
To activate it, run:
eval $(poetry env activate)
After this, you are inside the Poetry-managed environment.
You can now run Python directly:
python main.py
4. Run Without Activating
You can also run commands without manually activating the environment:
poetry run python main.py
5. Install All Dependencies
When you clone a project, simply run:
poetry install
It installs all the packages listed in pyproject.toml and poetry.lock.
📁 Poetry vs pip: Key Differences
| Feature | pip |
poetry |
|---|---|---|
| Dependency management | Manual via requirements.txt
|
Automatic via pyproject.toml and poetry.lock
|
| Virtual environments | You set it up yourself | Automatically created and managed |
| Adding packages | pip install |
poetry add |
| Removing packages | pip uninstall |
poetry remove |
| Dependency resolution | Basic | Advanced (checks compatibility) |
| Lock file | No built-in support | Yes (poetry.lock) |
| Project creation | Not available |
poetry new or poetry init
|
| Publishing to PyPI | Manual (twine etc.) | Built-in (poetry publish) |
In short, pip only installs packages. Poetry manages the whole project.
✅ Why Use Poetry?
Use Poetry if:
You want a clean and consistent environment
You are building a Python library or application
You want to avoid manually editing requirements files
You want built-in tools for versioning and publishing
Use pip if:
You're working on simple scripts
You don’t want extra tools
You prefer traditional virtualenv setups
pyproject.toml Example
[tool.poetry]
name = "my_project"
version = "0.1.0"
description = "My awesome Python project"
authors = ["Your Name <you@example.com>"]
[tool.poetry.dependencies]
python = "^3.10"
requests = "^2.31.0"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
This is what controls your project. It replaces setup.py, requirements.txt, and MANIFEST.in — all in one file.
🏁 Conclusion
Poetry upgrades your Python workflow. It takes care of dependencies, virtual environments, and even publishing. With just one command: eval $(poetry env activate), you can start coding without worrying about setup. While pip is great for simple tasks, Poetry is better for serious projects.
If you are tired of managing requirements.txt and venv by hand, try Poetry. It makes Python development faster, cleaner, and less frustrating.
Top comments (0)