Python pyenv and poetry Notes

Installing pyenv on Linux

Automatic Installation via pyenv-installer

$ # Use PYENV_GIT_TAG to install specific pyenv-installer version e.g.:
$ # export PYENV_GIT_TAG=v2.3.23
$ curl https://pyenv.run | bash

References

• pyenv bash installer

pyenv bash Environment

Add the following lines to ~/.bashrc (for interactive shells):

export PYENV_ROOT="${HOME}/.pyenv"
command -v pyenv >/dev/null || export PATH="${PYENV_ROOT}/bin:${PATH}"
eval "$(pyenv init -)"

Add the following lines to /.profile (for login shells):

export PYENV_ROOT="${HOME}/.pyenv"
command -v pyenv >/dev/null || export PATH="${PYENV_ROOT}/bin:${PATH}"
eval "$(pyenv init -)"

References

• pyenv Main Repository
• Common Python build problems
• Modern Python part 1: start a project with pyenv & poetry

Installing Python Build Dependencies

Ubuntu 22.04 LTS

# apt install make build-essential tk-dev libssl-dev libreadline-dev \
              libncurses-dev libbz2-dev zlib1g-dev libsqlite3-dev \
              libffi-dev liblzma-dev libxml2-dev libxmlsec1-dev xz-utils curl

References

• Suggested build environment

Building and Installing Python via pyenv

To list available Python versions:

$ pyenv install -l

To list installed Python versions and selected version:

$ pyenv versions

To install particular Python <version>:

$ pyenv install <version>

To select current Python <version>:

$ # global for current user account
$ pyenv global <version>

$ # current shell session
$ pyenv shell <version>

$ # current directory or its subdirectories
$ pyenv local <version>

To select system-installed Python version use <version> = system such as:

$ pyenv global system

References

• Install additional Python versions

Installing poetry on Ubuntu 22.04 LTS

Automatic User Account Installation

$ curl -sSL https://install.python-poetry.org | python -

Python Poetry automatic installation procedure had multiple backwards-deprecating changes over time. Thus, the following are manual installation instructions in case if the above automatic installation script gets deprecated once again.

Manual User Account Installation via pip with venv

Install poetry in a dedicated venv:

$ VENV_PATH=~/.local/share/pypoetry/venv
$ python -m venv $VENV_PATH
$ $VENV_PATH/bin/pip install -U pip setuptools
$ $VENV_PATH/bin/pip install poetry

Symlink installed poetry to a local bin directory:

$ ln -vs $VENV_PATH/bin/poetry ~/.local/bin

Test new poerty installation:

$ poetry --version
$ # expected output example:
$ # Poetry (version 1.4.2)

Enable bash tab completion:

$ poetry completions bash >> ~/.bash_completion

Poetry Python Version

Set Poetry to use specific Python <version>:

$ poetry env use <version>

Poetry Plugin up and Package Versions

up plugin updates dependencies and bumps their versions in pyproject.toml file. It works similar to yarn up command in Node.js. Install plugin:

$ poetry self add poetry-plugin-up

Update dependencies to latest available compatible versions:

$ poetry up --latest

Display the current and the latest version of the installed packages:

$ poetry show --latest

Display outdated packages only:

$ poetry show --outdated

Update <package> to the latest available version:

$ poetry add <package>@latest

poetry venv and VS Code

Installing venv in-project

Many (all?) VS Code extensions, by default, look for project Python virtual environment in <project-dir>/.venv. To install Python virtual environment in project directory use the following command:

$ poetry config virtualenvs.in-project true --local

Also when host has a system Python installation as well as pyenv installations, poetry might prefer pyenv even if system version is selected. To always prefer active python version use the following command:

$ poetry config virtualenvs.prefer-active-python true --local

Those commands should add the following content to <project-dir>/poetry.toml file:

[virtualenvs]
in-project = true
prefer-active-python = true

Then, run poetry install to create in-project virtual environment and install project dependencies there.

Pointing project config files to venv

By default, poetry installs project virtual environment in <user-home>/.cache/pypoetry/virtualenvs. To get current <project-venv> use the following command:

$ poetry env info -p

To configure VS Code extensions to use current <project-venv> add the following lines to .vscode/settings.json (assuming Python 3.11 is used):

{
  "python.pythonPath": "<project-venv>/bin/python",
  "ruff.path": [
    "<project-venv>/bin/ruff"
  ],
  "python.venvPath": "<user-home>/.cache/pypoetry/virtualenvs",
  "python.venvFolders": "<project-venv-name>",
  "python.analysis.typeCheckingMode": "strict",
  "python.analysis.extraPaths": [
    "<project-venv>/lib/python3.11/site-packages"
  ]
}

To configure Pyright (and Pylance) add the following lines to pyrightconfig.json (or to equivalent keys in pyproject.toml):

{
  "venvPath": "<user-home>/.cache/pypoetry/virtualenvs",
  "venv": "<project-venv-name>"
}

Manual VS Code Integration with venv of poetry Projects

1. Open terminal, navigate to the root directory of poetry project and activate poetry environment by running poetry shell
2. Notice virtual env path in terminal output
3. Open the command palette in VS Code by pressing Ctrl+Shift+P, run Python: Select Interpreter and select "Enter interpreter path..."
4. Navigate to the virtual env path and select python file
5. Current Python environment should be shown in the bottom right corner of VS Code window.

References

• Pyright Configuration