Guide: Setting Up Pyenv and Poetry on Linux-Based Systems¶

Introduction¶

Managing Python environments and dependencies effectively is essential for software development, particularly when working with multiple projects. This guide explains how to install and configure pyenv and Poetry on Linux-based systems (e.g., Linux or macOS).

!!! abstract "Why Use Pyenv with Poetry?" Poetry requires a Python version manager like pyenv to ensure compatibility and flexibility across different Python versions. Using pyenv, you can isolate Python versions per project, making dependency management with Poetry seamless and conflict-free.

Setting Up Pyenv on Linux-Based Systems¶

pyenv simplifies managing multiple Python versions, enabling you to switch between them easily. Follow the steps below to set up pyenv and configure it for use with Poetry.

Step 1: Install Prerequisites¶

Before installing pyenv, install the essential system packages:

sudo apt install curl git-core gcc make zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev libssl-dev

Step 2: Clone the pyenv Repository¶

Clone the official pyenv repository into your home directory:

git clone https://github.com/pyenv/pyenv.git $HOME/.pyenv

Step 3: Update Shell Configuration¶

To make pyenv accessible, modify your shell configuration file:

1. Open the .bashrc file (or .zshrc if using Zsh) with a text editor:

nano $HOME/.bashrc

1. Append the following lines to enable pyenv:

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
if command -v pyenv 1>/dev/null 2>&1; then
  eval "$(pyenv init -)"
fi

1. Save changes and exit the editor (Ctrl+X, Y, Enter in nano).

Step 4: Apply Changes¶

Reload the shell configuration to apply the changes:

source $HOME/.bashrc

Configuring Pyenv for Each Project¶

Step 1: Install Multiple Python Versions¶

Using pyenv, install all required Python versions for your projects:

pyenv install 3.9.7
pyenv install 3.10.13
pyenv install 3.11.5

You can verify the installed versions with:

pyenv versions

pyenv uninstall <version>

Step 2: Set the Python Version Per Project¶

For each project, specify the required Python version:

1. Navigate to the project directory:

cd /path/to/your/project

1. Use pyenv to set the local Python version:

pyenv local 3.10.13

This creates a .python-version file in the project directory, ensuring the specified version is activated when you work in the directory.

Installing and Configuring Poetry¶

Poetry simplifies dependency management and project setup. Using pipx, you can install Poetry in an isolated environment to avoid conflicts.

Step 1: Check or Install pipx¶

Ensure pipx is installed and updated:

pipx --version

If not installed, install or upgrade it:

python3 -m pip install --upgrade pipx

Step 2: Install Poetry¶

Install Poetry using pipx:

pipx install poetry

Step 3: Update Poetry (Optional)¶

Keep Poetry up-to-date with:

pipx upgrade poetry

Specifying Python Compatibility in pyproject.toml¶

While pyenv controls the actual Python version used in your environment, you can specify Python compatibility in the pyproject.toml file for consistency across collaborators. For example:

[tool.poetry.dependencies]
python = ">=3.10.0,<3.11"

Setting Up a Virtual Environment with Poetry¶

• Create Virtual Environment: Create an isolated environment for your project using Poetry:

poetry env use $(pyenv which python)

• Verify Python Version: Confirm Poetry is set to the desired Python version with:

poetry env info

• Install Dependencies: At your project root (where pyproject.toml is), run:

poetry install

• Activate Environment: Enter the environment with:

poetry shell

• Check Installation: Ensure all dependencies are installed:

poetry show

Conclusion¶

By combining pyenv and Poetry with project-specific configurations, you can efficiently manage Python versions and project dependencies.