Managing Virtual Environments With Poetry

00:00 In the last lesson, you learned about the pyproject .toml, understanding its content and what each section does. In this lesson, I’ll show you how to manage virtual environments with Poetry and why it’s such a great tool for keeping your Python environment organized.

00:16 When you create different Python projects, it’s good practice to also create associated virtual environments. This allows you to isolate the dependencies used in each project.

00:26 Poetry comes with built-in support for virtual environments to ensure that it never interferes with your global Python installation. By default, Poetry stores virtual environments in a system specific cache directory.

00:39 On Windows, you should find the virtual environment stored in a path on the `C:\Users\<username>\ `AppData\Local\pypoetry\Cache. For macOS they’re located in /Users /<username>/Library/Caches/` pypoetry/.

01:03 And for Linux, you can look in the directory /home/ /<username>/.cache/ pypoetry/. Each system keeps the environment separate, which helps maintain a clean Python setup.

01:18 If you’d like to change these locations, you can do so by editing Poetry’s configuration. A link describing how to do that and to learn more about these configurations is in the description under this video.

01:30 Now, to see your current configuration, including the virtual environment path, run poetry config --list.

01:40 You should see things like the cache directory, the virtualenvs path, and a host of other things. Most of the time, you wouldn’t need to change these paths, but it’s good to know where Poetry is storing your environments.

01:52 You can check which virtual environments Poetry is managing for your project, but first ensure you are in the project directory. If not, do so with the command cd for change directory and then your project name.

02:06 And then from there you can run the command poetry env list.

02:11 If you haven’t triggered Poetry to create a virtual environment yet, this command wouldn’t show anything as you should see no outputs yet. Later when you have multiple environments, you can use this to test your project across different Python versions or configurations.

02:27 Now, let’s go ahead to create a virtual environment. To have control over which Python version is used for your virtual environment, you can specify it upfront. To do that, run poetry env use python3.

02:41 You should see something like creating virtualenvs, your project name, some base64 hash code in your project cache directory path, and then Poetry tells you it’s now using that virtual environment.

02:55 You can replace python3 with any version you want, like be more specific with python3.12 or just python3. Note using bare python3 will work as long as you have the corresponding Python executable in your path.

03:12 All of this just ensures that the virtual environment that gets created uses a specific Python interpreter.

03:19 Now, to see which virtual environment is currently active, run the poetry env list command again. Poetry will not indicate which environment is active.

03:29 This doesn’t necessarily mean it’s traditionally activated in your shell. Instead, what Poetry does is it activates it temporarily when you run commands. To switch between environments when you run commands, you’ll use something like poetry env use 3.12.

03:46 You should see Using virtualenv, then your Poetry cache path. This is unchanged as the Python version specified is the same as was used before, which is 3.12.

03:59 Looking at your active virtual environment again,

04:03 Poetry generates a unique name for your virtual environment using your project’s name from your pyproject.toml file, the Python version, and the random string in the middle.

04:14 The random string in the middle is a base64 encoded hash that ties the virtual environment to your project’s location on disk. If I delete this virtual environment and recreate it as you are going to see shortly, this hash will remain the same as long as I am in the same location on my machine.

04:31 Also, if you move your project to another folder, Poetry will automatically create a new virtual environment for you and then that hash might change. If you want to delete or remove all environments connected to your project, you can run poetry env remove --all.

04:48 You should see Deleted virtualenv and then your user poetry env cache path.

04:55 If you run the poetry env list command, again, it should return nothing because you have just deleted the virtual environment. To activate it again, while in your project directory, you run poetry env use 3.12

05:11 and Poetry should create the virtual environment again. You can see the same base64 code confirming that we’re still creating the virtual environment for a project in the same location on disk.

05:22 To confirm our active environment, again, use the poetry env list command.

05:29 Like I said before, Poetry temporarily activates these environments to run commands, but you can persist your virtual environment activation to run code by running the command poetry shell.

05:42 You should see something like spawning shell within your user cache path, and this activates your virtual environment in shell, giving you a persistent environment to run your programs.

05:55 To deactivate this persistent virtual environment, you can run the command deactivate,

06:01 and this should take away the activated virtual environment from a persistent state. One thing to note is that the command deactivate if ran without an activated Poetry virtual environment might raise an error as there is no activated environment to deactivate.

06:15 In my case, I see command not found: deactivate. Also, to note the Python version you specify must meet the constraints in your pyproject.toml file.

06:26 If it doesn’t, Poetry will throw an error. Python 3.12 in my case is a version specifier, and what it means is that the project requires Python version 3.12 or any compatible future versions that doesn’t break backward compatibility with version 3.12.

06:44 With this knowledge, you are now ready to add dependencies to your project and let Poetry manage everything for you and you and I will do just that in the next lesson.