Virtual Environments¶

When you work in Python projects you probably should use avirtual environment (or a similar mechanism) to isolate the packages you install for each project.

Create a Project¶

First, create a directory for your project.

What I normally do is that I create a directory namedcode inside my home/user directory.

And inside of that I create one directory per project.

// Go to the home directory$cd// Create a directory for all your code projects$mkdircode// Enter into that code directory$cdcode// Create a directory for this project$mkdirawesome-project// Enter into that project directory$cdawesome-project

Create a Virtual Environment¶

When you start working on a Python projectfor the first time, create a virtual environmentinside your project.

$python-mvenv.venv

$uvvenv

That command creates a new virtual environment in a directory called.venv.

Activate the Virtual Environment¶

Activate the new virtual environment so that any Python command you run or package you install uses it.

$source.venv/bin/activate

$.venv\Scripts\Activate.ps1

$source.venv/Scripts/activate

Check the Virtual Environment is Active¶

Check that the virtual environment is active (the previous command worked).

$whichpython/home/user/code/awesome-project/.venv/bin/python

$Get-CommandpythonC:\Users\user\code\awesome-project\.venv\Scripts\python

Upgradepip¶

If you are usingpip to install packages (it comes by default with Python), you shouldupgrade it to the latest version.

Many exotic errors while installing a package are solved by just upgradingpip first.

Make sure the virtual environment is active (with the command above) and then run:

$python-mpipinstall--upgradepip---> 100%

Add.gitignore¶

If you are usingGit (you should), add a.gitignore file to exclude everything in your.venv from Git.

$echo"*">.venv/.gitignore

*

Install Packages¶

After activating the environment, you can install packages in it.

Install Packages Directly¶

If you're in a hurry and don't want to use a file to declare your project's package requirements, you can install them directly.

$pipinstallsqlmodel---> 100%

$uvpipinstallsqlmodel---> 100%

Install fromrequirements.txt¶

If you have arequirements.txt, you can now use it to install its packages.

$pipinstall-rrequirements.txt---> 100%

$uvpipinstall-rrequirements.txt---> 100%

sqlmodel==0.13.0rich==13.7.1

Run Your Program¶

After you activated the virtual environment, you can run your program, and it will use the Python inside of your virtual environment with the packages you installed there.

$pythonmain.pyHello World

Configure Your Editor¶

You would probably use an editor, make sure you configure it to use the same virtual environment you created (it will probably autodetect it) so that you can get autocompletion and inline errors.

For example:

• VS Code
• PyCharm

Deactivate the Virtual Environment¶

Once you are done working on your project you candeactivate the virtual environment.

$deactivate

This way, when you runpython it won't try to run it from that virtual environment with the packages installed there.

Ready to Work¶

Now you're ready to start working on your project.

Why Virtual Environments¶

To work with SQLModel you need to installPython.

After that, you would need toinstall SQLModel and any otherpackages you want to use.

To install packages you would normally use thepip command that comes with Python (or similar alternatives).

Nevertheless, if you just usepip directly, the packages would be installed in yourglobal Python environment (the global installation of Python).

The Problem¶

So, what's the problem with installing packages in the global Python environment?

At some point, you will probably end up writing many different programs that depend ondifferent packages. And some of these projects you work on will depend ondifferent versions of the same package. 😱

For example, you could create a project calledphilosophers-stone, this program depends on another package calledharry, using the version1. So, you need to installharry.

flowchart LR    stone(philosophers-stone) -->|requires| harry-1[harry v1]

Then, at some point later, you create another project calledprisoner-of-azkaban, and this project also depends onharry, but this project needsharry version3.

flowchart LR    azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3]

But now the problem is, if you install the packages globally (in the global environment) instead of in a localvirtual environment, you will have to choose which version ofharry to install.

If you want to runphilosophers-stone you will need to first installharry version1, for example with:

$pipinstall"harry==1"

And then you would end up withharry version1 installed in your global Python environment.

flowchart LR    subgraph global[global env]        harry-1[harry v1]    end    subgraph stone-project[philosophers-stone project]        stone(philosophers-stone) -->|requires| harry-1    end

But then if you want to runprisoner-of-azkaban, you will need to uninstallharry version1 and installharry version3 (or just installing version3 would automatically uninstall version1).

$pipinstall"harry==3"

And then you would end up withharry version3 installed in your global Python environment.

And if you try to runphilosophers-stone again, there's a chance it wouldnot work because it needsharry version1.

flowchart LR    subgraph global[global env]        harry-1[<strike>harry v1</strike>]        style harry-1 fill:#ccc,stroke-dasharray: 5 5        harry-3[harry v3]    end    subgraph stone-project[philosophers-stone project]        stone(philosophers-stone) -.-x|⛔️| harry-1    end    subgraph azkaban-project[prisoner-of-azkaban project]        azkaban(prisoner-of-azkaban) --> |requires| harry-3    end

Now, imagine that withmany otherpackages that all yourprojects depend on. That's very difficult to manage. And you would probably end up running some projects with someincompatible versions of the packages, and not knowing why something isn't working.

Also, depending on your operating system (e.g. Linux, Windows, macOS), it could have come with Python already installed. And in that case it probably had some packages pre-installed with some specific versionsneeded by your system. If you install packages in the global Python environment, you could end upbreaking some of the programs that came with your operating system.

Where are Packages Installed¶

When you install Python, it creates some directories with some files in your computer.

Some of these directories are the ones in charge of having all the packages you install.

When you run:

// Don't run this now, it's just an example 🤓$pipinstallsqlmodel---> 100%

That will download a compressed file with the SQLModel code, normally fromPyPI.

It will alsodownload files for other packages that SQLModel depends on.

Then it willextract all those files and put them in a directory in your computer.

By default, it will put those files downloaded and extracted in the directory that comes with your Python installation, that's theglobal environment.

What are Virtual Environments¶

The solution to the problems of having all the packages in the global environment is to use avirtual environment for each project you work on.

A virtual environment is adirectory, very similar to the global one, where you can install the packages for a project.

This way, each project will have its own virtual environment (.venv directory) with its own packages.

flowchart TB    subgraph stone-project[philosophers-stone project]        stone(philosophers-stone) --->|requires| harry-1        subgraph venv1[.venv]            harry-1[harry v1]        end    end    subgraph azkaban-project[prisoner-of-azkaban project]        azkaban(prisoner-of-azkaban) --->|requires| harry-3        subgraph venv2[.venv]            harry-3[harry v3]        end    end    stone-project ~~~ azkaban-project

What Does Activating a Virtual Environment Mean¶

When you activate a virtual environment, for example with:

$source.venv/bin/activate

$.venv\Scripts\Activate.ps1

$source.venv/Scripts/activate

That command will create or modify someenvironment variables that will be available for the next commands.

One of those variables is thePATH variable.

Activating a virtual environment adds its path.venv/bin (on Linux and macOS) or.venv\Scripts (on Windows) to thePATH environment variable.

Let's say that before activating the environment, thePATH variable looked like this:

/usr/bin:/bin:/usr/sbin:/sbin

C:\Windows\System32

After activating the virtual environment, thePATH variable would look something like this:

/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin

/home/user/code/awesome-project/.venv/bin

/home/user/code/awesome-project/.venv/bin/python

C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32

C:\Users\user\code\awesome-project\.venv\Scripts

C:\Users\user\code\awesome-project\.venv\Scripts\python

An important detail is that it will put the virtual environment path at thebeginning of thePATH variable. The system will find itbefore finding any other Python available. This way, when you runpython, it will use the Pythonfrom the virtual environment instead of any otherpython (for example, apython from a global environment).

Activating a virtual environment also changes a couple of other things, but this is one of the most important things it does.

Checking a Virtual Environment¶

When you check if a virtual environment is active, for example with:

$whichpython/home/user/code/awesome-project/.venv/bin/python

$Get-CommandpythonC:\Users\user\code\awesome-project\.venv\Scripts\python

That means that thepython program that will be used is the onein the virtual environment.

you usewhich in Linux and macOS andGet-Command in Windows PowerShell.

The way that command works is that it will go and check in thePATH environment variable, going througheach path in order, looking for the program calledpython. Once it finds it, it willshow you the path to that program.

The most important part is that when you callpython, that is the exact "python" that will be executed.

So, you can confirm if you are in the correct virtual environment.

Why Deactivate a Virtual Environment¶

For example, you could be working on a projectphilosophers-stone,activate that virtual environment, install packages and work with that environment.

And then you want to work onanother projectprisoner-of-azkaban.

You go to that project:

$cd~/code/prisoner-of-azkaban

If you don't deactivate the virtual environment forphilosophers-stone, when you runpython in the terminal, it will try to use the Python fromphilosophers-stone.

$cd~/code/prisoner-of-azkaban$pythonmain.py// Error importing sirius, it's not installed 😱Traceback (most recent call last):    File "main.py", line 1, in <module>        import sirius

But if you deactivate the virtual environment and activate the new one forprisoner-of-askaban then when you runpython it will use the Python from the virtual environment inprisoner-of-azkaban.

$cd~/code/prisoner-of-azkaban// You don't need to be in the old directory to deactivate, you can do it wherever you are, even after going to the other project 😎$deactivate// Activate the virtual environment in prisoner-of-azkaban/.venv 🚀$source.venv/bin/activate// Now when you run python, it will find the package sirius installed in this virtual environment ✨$pythonmain.pyI solemnly swear 🐺

Alternatives¶

This is a simple guide to get you started and teach you how everything worksunderneath.

There are manyalternatives to managing virtual environments, package dependencies (requirements), projects.

Once you are ready and want to use a tool tomanage the entire project, packages dependencies, virtual environments, etc. I would suggest you tryuv.

uv can do a lot of things, it can:

• Install Python for you, including different versions
• Manage thevirtual environment for your projects
• Installpackages
• Manage packagedependencies and versions for your project
• Make sure you have anexact set of packages and versions to install, including their dependencies, so that you can be sure that you can run your project in production exactly the same as in your computer while developing, this is calledlocking
• And many other things

Conclusion¶

If you read and understood all this, nowyou know much more about virtual environments than many developers out there. 🤓

Knowing these details will most probably be useful in a future time when you are debugging something that seems complex, but you will knowhow it all works underneath. 😎