Python Packaging and Management

Developers come across the scenario of switching between multiple versions of interpreters, simply because the project they work on requires different interpreter versions and also different bunch of libraries. In python, luckily, we can use pyenv to manage multiple interpreter versions and further create virtual environments for every projects to help us not pollute the global space.

Switching Python Versions

Global (system-wide default)

pyenv global 3.12.1

pyenv global 3.12.1

Per-project (recommended)

cd my_project
pyenv local 3.12.1

cd my_project
pyenv local 3.12.1

This creates:

.python-version

Commit this file to your repo.

Per-shell (temporary)

pyenv shell 3.10.13

pyenv shell 3.10.13

Poetry is a modern Python tool that:

• Manages project dependencies
• Creates and manages virtual environments
• Builds and publishes Python packages
• Replaces pip, virtualenv, and setup.py with one unified system

Think of it as npm for Python, but opinionated and reproducible.

Why Poetry Exists (the problem it solves)

Traditional Python workflow:

pip install requests
pip freeze > requirements.txt
virtualenv venv
source venv/bin/activate

Problems:

• requirements.txt doesn’t lock versions well
• Virtual environments are manual
• Packaging is confusing (setup.py, setup.cfg, MANIFEST.in)
• Reproducing environments is unreliable

Core Concepts

pyproject.toml

Poetry stores everything in one file:

[tool.poetry]
name = "my-project"
version = "0.1.0"

[tool.poetry.dependencies]
python = "^3.12"
requests = "^2.31.0"

This replaces:

• requirements.txt
• setup.py
• setup.cfg

poetry.lock

This file pins exact versions so everyone installs the same packages.

Creating a New Project

poetry new my_project
cd my_project

poetry new my_project
cd my_project

Or initialize in an existing folder:

poetry init

poetry init

Installing Dependencies

Add a package

poetry add requests

poetry add requests

Add dev dependency

poetry add --group dev pytest black

poetry add --group dev pytest black

Remove package

poetry remove requests

poetry remove requests

Virtual Environment Commands

Activate shell

poetry shell

poetry shell

Run command without activating

poetry run python main.py
poetry run pytest

poetry run python main.py
poetry run pytest

Show environment info

poetry env info

poetry env info

List environments

poetry env list

poetry env list

Remove environment

poetry env remove python

poetry env remove python

Installing Project Dependencies

poetry install

poetry install

Dependency Locking

Update dependencies (respecting version ranges)

poetry update

poetry update

Update one package

poetry update requests

poetry update requests

Packaging & Publishing

Build package

poetry build

poetry build

Publish to PyPI

poetry publish

poetry publish

Useful Utility Commands

Common Workflow

poetry init
poetry add fastapi uvicorn
poetry shell
python main.py

poetry init
poetry add fastapi uvicorn
poetry shell
python main.py

Or in CI:

poetry install --no-dev
poetry run python app.py

poetry install --no-dev
poetry run python app.py

Poetry Configuration (Advanced & Useful)

# List all configs
poetry config --list

# List all configs
poetry config --list

They can be:

• global (default)
• local (--local, per project)

# Virtualenv Behavior
poetry config virtualenvs.create true
# Create virtualenvs automatically in the project root
poetry config virtualenvs.in-project true
# Create .venv/ inside project
poetry config virtualenvs.path "/custom/path"

# Virtualenv Behavior
poetry config virtualenvs.create true
# Create virtualenvs automatically in the project root
poetry config virtualenvs.in-project true
# Create .venv/ inside project
poetry config virtualenvs.path "/custom/path"