DEV Community

João Maranhão
João Maranhão

Posted on


Simplifying Python Development: A Step-by-Step Guide to Setting up a Python Project with Git and GitHub

The purpose of this article is to provide a clear path and understanding of how you would set up a Python environment on your machine.

Keep in mind that the following content is written thinking on a Linux environment. If you use another OS, make the necessary changes.

Install Python

Install pyenv

GitHub - pyenv/pyenv: Simple Python version management

This allows you to simply choose the Python version you want to use. It allows you to set the global version for the system or a local version for specific projects or directories.

Use pyenv to install Python

Once pyenv is installed, you can use it to install the version of Python you want to use.

You can also use pyenv local command to set a local version of Python for a specific directory, this way you can have a different version of Python for different projects.

To test your installation, you can open a terminal and run the following command:

python --version
Enter fullscreen mode Exit fullscreen mode

This should print the version of Python you have installed, which should be the version you set using pyenv.

Install pip

pip is a package manager for Python that makes it easy to install and manage packages. It is included with Python 3.4 and later, so you don't need to install it separately.

If your python version is less than 3.4 then you need to install pip separately

Create and activate a virtual environment

A virtual environment is an isolated environment where you can install packages without interfering with the system-wide packages. To create a virtual environment, you can use the venv package.

In your project’s directory, run the following command:

python -m venv venv
Enter fullscreen mode Exit fullscreen mode

This will create a new directory called venv on your current working directory, where you can install your packages.

To activate your virtual environment, you need to run the following command:

source venv/bin/activate
Enter fullscreen mode Exit fullscreen mode

Once your virtual environment is active, you should see the name of the environment in the terminal prompt, indicating that it is active. Any packages you install while the environment is active will be installed in the venv directory and will not affect other projects or your system Python installation.

Use Git to manage your project

Install Git

The process to install Git on Linux can vary depending on the distribution you are using. You can use the package manager specific to your distribution to install Git.

For example, on Ubuntu or Debian, you can use the apt-get command:

sudo apt-get install git
Enter fullscreen mode Exit fullscreen mode

On Fedora or CentOS, you can use the yum command:

sudo yum install git
Enter fullscreen mode Exit fullscreen mode

Once Git is installed, you can check its version running:

git --version
Enter fullscreen mode Exit fullscreen mode

This should print the version of Git installed on your machine.

Start a local Git repository

To start a local Git repository for your project, you can follow these steps:

git init
Enter fullscreen mode Exit fullscreen mode

This command will create a new .git directory in your project, which will store all the information about your repository, such as the history of commits and the current state of the project.

Add Python’s .gitgnore

You can download Python’s .gitignore from Github by entering this command on your terminal:

wget -O .gitignore
Enter fullscreen mode Exit fullscreen mode

Now we can stage and commit the .gitignore file to our local repository by running these commands:

git add .gitignore
git commit -m "chore: add .gitignore"
Enter fullscreen mode Exit fullscreen mode

It's also a good practice to review the contents of the .gitignore file downloaded from Github and modify it as per your specific use case.

You can also add additional files or directories that you want to ignore in your project by modifying the contents of the .gitignore file and then committing the changes to the repository. This way, you can ensure that the files you want to ignore are consistently excluded from your Git repository in all branches.

You can use conventional commits in your Git repository to make it easier to understand and track the changes that have been made to the code.

Conventional Commits

Install black to code formatting

Black can be installed by running pip install black. It requires Python 3.7+ to run.

VS Code

If you use VS Code, you can add to your configuration file the following:

    "python.formatting.provider": "black",
    "editor.formatOnSave": true
Enter fullscreen mode Exit fullscreen mode

Don’t forget to also install the recommended Python extensions.

Create a requirements.txt file

To create a requirements.txt file, you can use the following command:

pip freeze > requirements.txt
Enter fullscreen mode Exit fullscreen mode

This will create a file called requirements.txt in the current directory and list all the packages with versions that are installed in your environment.

Add the requirements.txt file to the repository by running git add requirements.txt

Commit the file to the repository by running git commit -m "chore: add requirements.txt"

Create a GitHub repository

Go to the GitHub website ( and sign in to your account.

Click on the "+" button in the top right corner of the page, and select "New repository" from the menu. Give a name to your repository and an optional description and choose whether you want your repository to be public or private.

Add the remote repository on GitHub using the command:

git remote add origin, replace yourusername with your github username.

Finally, push your local repository to the newly created GitHub repository by running:

git push -u origin main or any other branch name you want to push.


In conclusion, setting up a Python project with Git and GitHub is relatively easy to do.

By following the steps outlined in this article, you'll be able to set up a clean and organized environment for your Python projects, regardless of the operating system you're using.

The important thing to keep in mind is to review the steps and make any necessary adjustments depending on the operating system you are using.

If you have any questions, suggestions or just want to say hi, feel free to reach out to me!

Follow me on Twitter!

Top comments (0)

50 CLI Tools You Can't Live Without

>> Check out this classic DEV post <<