How to Set the Python Version Using asdf and Poetry on macOS?

How to Set the Python Version Using asdf and Poetry on macOS?

In the world of Python development, managing different Python versions for various projects can be a daunting task. Fortunately, tools like asdf and Poetry make this process much more manageable. In this guide, we will walk you through the steps to set up and use asdf and Poetry to manage Python versions on macOS.


This article is very subjective. If you do not feel comfortable viewing it, please close it as soon as possible.
If you think my article can help you, you can subscribe to this site by using RSS.

Installing and Setting up asdf

asdf is a version manager that allows you to manage multiple runtime versions. Here’s how you can set it up:

  1. Install asdf by following the official installation guide.

  2. Install the asdf Python plugin, which will enable you to manage Python versions with asdf. You can find the plugin on GitHub: asdf-python.

After setting up asdf and install many Python versions, you can list the available Python versions using the following command:

asdf list python

This will display a list of installed Python versions, and the currently selected version will be marked with an asterisk (*).

For example the list in my macOS

asdf list python

Installing and Setting up Poetry

Poetry is a dependency and package management tool for Python projects. Here’s how to set it up:

  1. Install Poetry by following the official installation guide.

Note: If you use the fish shell, be aware that there might be completion issues with Poetry as of September 13, 2023.

Creating a Python Project with Poetry

Now that both asdf and Poetry are set up, let’s create a Python project with Poetry and specify the Python version for the project.

  1. Create a new Python project using Poetry. In this example, we’ll name it poetry-demo-py39 and set the Python version to 3.9.17:
poetry new poetry-demo-py39
  1. Navigate to the project directory:
cd poetry-demo-py39/

Managing Python Versions with asdf and Poetry

Step 1: Update pyproject.toml

Open the pyproject.toml file in your favorite text editor. This file defines project metadata and dependencies. Modify it to specify the desired Python version:

name = "poetry-demo-py39"
version = "0.1.0"
description = ""
authors = ["Your Name <>"]
readme = ""

python = "^3.9"

Step 2: Set the Local Python Version with asdf

Use asdf to set the local Python version to 3.9.17. This ensures that the project uses the specified Python version:

asdf local python 3.9.17

Step 3: Set Poetry Environment

Next, set up the Poetry environment to align with the selected Python version:

poetry env use 3.9.17

This command creates a virtual environment for your project based on the specified Python version.

To verify that everything is working correctly, enter the Poetry shell:

poetry shell
python --version

You should now be in a shell with the correct Python version:

Python 3.9.17

Congratulations! You’ve successfully set up your Python project to use a specific Python version with asdf and Poetry.


Managing Python versions in your projects is essential for maintaining compatibility and ensuring that your code runs smoothly. With the help of asdf and Poetry, you can easily switch between Python versions and create isolated environments for your projects. This approach improves the stability and maintainability of your Python development workflow.

Now that you have the tools and knowledge, go ahead and enjoy hassle-free Python version management with asdf and Poetry!

How to Set the Python Version Using asdf and Poetry on macOS?


Ewan Xiao

Posted on

September 13th 2023

Updated on

September 28th 2023

Licensed under