MacOS / Linux: How to start a new Python 3 project using VENV Virtual Environment

How to set-up a Python Virtual Environment

I thought I would write a brief blog to capture the notes I use when I create a new Python 3 project. I’m working on MacOS but the process should be the same on other Unix/Linux based systems and the principles should be the same if you are working on Windows.

Step 1: Create a new directory to house your project

mkdir my-project

cd my-project

Step 2: Create a Python virtual environment so we can create a local set of dependancies for this project.

python3 -m venv venv --prompt Descriptive-Name

The Descriptive Name is optional, but recommended when you are working across projects in lots of different environments. It helps to make the command line prompt more distinctive so you are sure which environment you are in.

Step 3: Activate your virtual environment

source venv/bin/activate

After doing this you can confirm at anytime which Python environment you are using with the following command

which python

Just have a look at the directory path that is returned and confirm it is a sub-directory of the directory you created in step 1 above.

Step 4: If you have a ‘requirements.txt’ listing the dependancies for the new project run it now.

pip install -r requirements.txt

check the list afterwards using pip list

If you don’t have a requirements.txt and you want to package up an existing project to install into this new environment, please see below – how to package a python project.

Step 5: Create some new Python source

Don’t put your own source in the venv directory, keep it in the parent directory. For example

cd my-project

The code command is the command line shortcut to launch Microsoft Visual Studio Code.

Selecting your Python Virtual Environment is MS Code Studio

Step 6: If you are using VS Code, it doesn’t seem to detect the virtual environment automatically all the time. So you need to manually tell it which environment to use for your code.

In Code do CMD-SHIFT-P then search for Python: Select Interpreter. Look down the list and select the Python executable in the venv directory we created in step 2.

Note: May 2021: The above method of setting the Python Environment is MS Visual Code always worked for me, but with the latest release I fear this may have been broken by a bug or a conflict somewhere. If this doesn’t work for you, simply find or create the settings.json file in your projects .vscode directory and add the following configuration entry, to point the project to the python interpreter you created above.

    "python.pythonPath": "/Users/linda/Documents/it-management/my-project/venv/bin/python3"

Setting up GIT Version control for your Python Project

Step 7: Set-up GIT version control and omit the venv directory in your .getignore file.

git init

Then create a file called .gitignore in the projects root directory and add all the files and directories that you don’t want version tracked, for example:


How to package a Python project

If you want to be able to package your Python project so that you can transfer it to another machine / server you first need to understand the dependancies your project has. This in simple terms means the various packages you’ve installed with pip.

To do this you can use the pip freeze

pip freeze > requirements.txt

This creates a simple text file listing all the packages which are part of your project and their versions. This can then be fed into the pip install process.


  • If you want to leave your VENV virtual environment at any time, you can either switch to another environment using the activate step shown above or you can exit completely back to your systems default Python using the deactivate command.
  • If you don’t have the VENV command installed in your Python environment use the command pip3 install virtualenv to install it.
  • There is a good example of a complete / best practice Python .getignore file here

You May Also Like…

Find similar blogs in these categories: Python
Submit a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.