New Python Projects - environment setup

By rcwd, Mon 08 April 2019, in category Python

git, pipenv

During a recent chat at the Jersey Python User Group, we discussed the various approaches to starting and managing a new project. I figured it would be worth noting down my current workflow for a new project.

Bear in mind I'm very terminal focussed in my development, preferring command line tooling over GUI in most aspects of working with code. This is not to say there aren't other options (some are explored at the end of this post) but this represents my personal preference to project set up.

New directory

Step one - the project needs somewhere to live so spin up a new directory in my ~/src/ folder. Disk is cheap so this tends to be the first step wether the project is planned to be huge, or a couple of lines to test something out.

mkdir ~/src/my_new_project  
cd ~/src/my_new_project

Note the project directory is always lower case and doesn't have any spaces. Also ensure that the project doesn't clash with any module names!

New virtual env

While I've been using virtual environments for a while now, I'm a fairly recent convert to PipEnv. For the uninitiated, Pipenv is a tool that aims to bring the best of all packaging worlds (bundler, composer, npm, cargo, yarn, etc.) to the Python world. You don't necessarily need to know what that all means, suffice to say Pipenv will make your life a lot easier by ensuring you have separate modules, Python versions for each project you write.

If you're not convinced, let me ask you this? Would you try and code with all of the files in the same directory for every project? I'm going to assume not, so why would you use the same module set?

pipenv install

The one gotcha (in the lightest possible sense) is that you need to activate your virtual environment before using it. So ensure you run

pipenv shell

before running your code.

Python File

It might sound obvious but I'm going to need somewhere to drop some code. And this means a single python file to get started:


I tend to use as my entry point to any application. I do a bit of Flask development so this convention is useful there. And the file always has the same basic starting point:

#!/usr/bin/env python

from __future__ import print_function
import logging
import pprint
import sys

def main():

if __name__ == '__main__':

My *nix Shebang, Some standard imports, a main method and the magical wiring to allow the script to be called. Sorted!

It's worth noting that this is purely a starting point, more often that not other files & directories will be added very quickly (a for environment variables, a lib directory for custom modules) but this is the bare minimum.


The final step is to ensure the project is under version control from day one. It might seem a bit silly to do this for every bit of code but it provides a massive amount of protection should the project become something more, and it's generally good practice as part of your development workflow (opinionated? yes, but I will defend the use of version control to the death so don't at me!)

First thing we need is actually a .gitignore file. I normally use this one from Github as a starting point but ensure you read through and comment out anything that might cause you issues.

Once the .gitignore is in place it's time to initialize the repository:

git init

And add all our files:

git add ./
git commit -am 'Initial Commit'

Finally I tend to create a new "develop" branch to keep all of my hacking off master:

git checkout -b

For more on why I do this I'd suggest you read up on Git Branching Models and how they impact workflow. It's also worth nothing that, once a project reaches a certain size, I 'll nearly always switch it to the Git Flow branching model so having develop up front ensures an easy transition down the line.


That's it, one basic project ready to rock and roll. While this may seem like a lot of steps it's actually little more than a minute's work:


While this is my preferred approach, there are other options depending your level of experience with the command line, the tools you prefer to use and the nature of the work you're doing.

PyCharm has full project management built in including virtual environment management, version control and more.

Alternatively you may have the Anaconda project installed which supplies a different slant on virtual envs and comes with a load of powerful tooling out of the box, especially (but not solely) if you're working with data science tools.

What ever you use I'd encourage you to give some serious thought to ensuring you have a virtual environment and versoin control configured for every project - it might seem like overkill at first but it's super easy and trust me when I say, you'll definitely thank me at some point 😎