Setting up a python development environment

Photo by David Clode on Unsplash

I’ve recently started becoming reacquainted with python after a very long time. I want to share a simple post on setting up an environment for python development.

In my example, I’m assuming you are using either a Linux distro (I’m using Ubuntu 18) or the Ubuntu 18 WSL (on Windows 10). There wouldn’t be many changes if you are using a Mac.

I’m going to describe setting up a local development environment (using virtual environments), because it is nice to learn, and comes in handy when you develop lots of different python projects on a single machine and may want to use different versions of packages in different projects.

The things we’ll cover are:

1. Installing python3 (3.3+)
2. Creating virtual environments with python3 -m venv
3. Activating and deactivating virtual environments
4. Installing dependencies with pip in the virtual environment
5. Running applications in the activated virtual environment
6. Collaborating on projects (what to store in the cloud, and how to let others know what is needed to run your application)

I’ll cover these items with a simple example to demonstrate the concepts.

Installing python3

The steps for installing python in Ubuntu are simple:

1. See if it’s already installed: python3 -V
   If it returns a version, and that version is 3.5 or higher, you are done!
2. If it isn’t installed (the command returns an error or nothing), use apt to install:
   sudo apt-get update
   sudo apt-get install python3
3. If it is already installed, but the version is less than 3.5, then upgrade it:
   sudo apt-get update
   sudo apt-get upgrade python3

Note: If you look at other resources, they may mention installing pip, but python 3.4 and later include pip by default.

Important: On Ubuntu, if you run python instead of python3, you will be running the 2.7 version of python (by default). Make sure when you run a python script or command, you always using python3.

Here’s an article on installing python3 on MacOS.

Create a project directory

I’ll do a simple hello world in this post, so create a directory called hello-python somewhere on your system. I have a projects directory in my home directory, so I’m going to create it there:

mkdir ~/projects/hello-python

Creating virtual environments for python3

Some people like to use pipenv to manage virtual environments, but I had some frustration with it. You can read more detail about how to install and use pipenv on Ubuntu here if you’re interested.

Instead I’ll describe how to use venv directly (the python3 version of virtualenv).

There are a number of ways to manage virtual environments for python, and some debate about which is best. In truth, which way is best depends on the situation. In this post, I’m going to suggest putting the virtual environment inside of the project directory. The reasons are:

1. It makes collaboration easier (you can just add the venv directory to your .gitignore, and anyone who pulls down your project can generate their own)
2. You can replace/recreate your virtual environment without disturbing your project files
3. The virtual environment is directly co-located with your project, which feels like a cleaner and easier to understand implementation to me for a beginner

Note: I’m suggesting using at least python 3.5 because using the venv module to create virtual environments is recommended with python 3.5 and later.

You can create a simple, lightweight, project virtual environment with python 3.3 and later using the venv module. First change to your project directory, then run the command shown:

cd ~/projects/hello-python
python3 -m venv venv

This will create a subdirectory in ~/projects/hello-python named venv. It is a common convention to call the virtual environment directory venv when created as a subdirectory of a project.

You can learn more about what is in this venv directory on your own, but what you need to know for now is that it will be where any dependencies for your project are installed, and it will be used to set path variables used by python when it is activated that allow your application to run with those dependencies.

At any time, you can just remove this venv directory and recreate it, using the steps shown here. Remember that if you do, you will have to reinstall any dependencies with pip install after recreating and activating the venv. We’ll look at activating and deactivating a virtual environment to use it next.

Activating and deactivating a virtual environment

To install dependencies for your projects in your virtual environment, and to run your application using those dependencies, you have to activate the environment. As mentioned, this will set path variables required for those dependencies to be used.

To activate your virtual environment, from your project directory, simply run:

source venv/bin/activate

Once you do this, you will see an indication that the virtual environment is being used:

(venv) ~/projects/hello-python

When you are finished working on your application, you should deactivate the virtual environment with the deactivate command:

deactivate

Installing dependencies

To install dependencies, activate the virtual environment in your project directory first. When this is done, a pip install will install the dependency in that virtual environment (instead of globally). For our hello-python project, we will install pyfiglet to create an ASCII art “hello”:

cd ~/projects/hello-python
source venv/bin/activate
pip install pyfiglet

Write and run the application

The code we write will be very simple in this post, because we are focusing on the setup and management of a python project using virtual environments. Create and open a file called hello-python.py in your ~/projects/hello-python directory. I’m going to use VSCode. I’m assuming your virtual environment is already activated (from the previous step) and that you are already in your project directory:

code hello-python.py

Add these lines to that file, then save it:

import pyfiglet
hello_ascii = pyfiglet.figlet_format(“Hello!”)
print(hello_ascii)

See if it works! Run your application with:

python hello-python.py

You should see something like this:

Expected output of python hello-python.py

A couple of things to note:

We didn’t have to run ‘python3 hello-python.py’, why?
Because we have activated the venv, which is using the python executable in our venv path. That python executable points to python3, because we created the venv with python3. You can see this if you run which python and python -V. You should see something like this:

Output of ‘which python’ and ‘python -V’ in activated venv

The pyfiglet module is available because we have the venv activated. If we deactivate, our application won’t run because the dependency will not be available. Try it:

deactivate
python hello-python.py

You should see something like this:

Output when venv is deactivated — application doesn’t run

Storing our project in the cloud (GitHub)

I won’t go into detail in this post about using GitHub (I may write another simple Git/GitHub post, but there are plenty of good resources out there, like this one.)

If you look in the venv directory in your project, you’ll notice there’s a lot of stuff in there, about 12MB of stuff on my system. There is no need to push all that up to your repository. Instead, just add venv to your .gitignore:

Add venv to .gitignore in project directory

In your README.md, add the list of dependencies for your application. This will allow anyone who pulls down your project to know what needs to be installed for it to run (including your future self). In this case, the only dependency is pyfiglet. You can use the command pip list in your activated venv to get a list of installed modules (or just look at what you import into your application files). Note that some of the installed modules shown by pip list come by default and are not explicitly installed by you.

Now, go play!

I hope you find this post helpful and were successful in following along. If you have questions, you can follow me and send me a message in Twitter at @JanelBrandon12.