Skip to content

Python: Create a project with Poetry and add it to GitHub

Jump to bottom
Neil Johnson edited this page Mar 8, 2022 · 2 revisions

Poetry is a complete Python dependency management, virtual environment, and packaging tool that can replace a multitude of Python tools and configuration files. Poetry uses the pyproject.toml file to maintain all of the project and build information you need to create, maintain, and publish your Python package.

So, what if you want to create a Python project with Poetry, and then commit it to a GitHub repository ("repo")? This how-to guide will show you how.

Before you start

Before starting these steps, you'll need the following software correctly installed on your development workstation. These instructions apply to Windows, Mac and Linux computers.

This how-to guide assumes that you are already comfortable:

  • writing code in Python
  • Using GitHub and git
  • working on the command line

If you check all these boxes, let's get started.

Using Poetry with GitHub: Overview

Here's an overview of the steps you'll need to complete to use Poetry to create, manage, and publish your new Python package, and commit your project to a GitHub repository.

  1. Create a new Python project on your development workstation using Poetry.
  2. Commit your new Python project to git on your local development workstation.
  3. Add your new git repo to GitHub with GitHub Desktop.
  4. Update your Poetry project with packages.
  5. Commit your changes to GitHub.

That's all there is to it. Once you've added your local git repo to GitHub, you can collaborate with other developers and clone your code to other computers. Let's look at the each step in detail.

Create a new Python Project with Poetry

Wheb you use Poetry to create a new Python project on your development workstation, Poetry will create a project directory and set up all the files and subdirectories you need to build and publish your new Python package. Poetry will also create a virtual environment, manage all of the packages you need to import, and track all the project configuration information in your new pyproject.toml file.

First, you need to create or select a directory to contain your new Python project. Since this is going to be a git (and also GitHub) repo, I like to put these types of projects in ~/repos -- although you can use any directory on your computer you want. As long as you have read and write access, you should be all set. Since you're going to be sharing your code with GitHub, I'd avoid putting your new repo in a "sync" folder, like Dropbox or Google Drive. Also, use a local directory -- putting your git repo on a shared network drive basically defeats the point of using git in the first place.

To create your new Python project with Poetry, enter these commands (I'm going to use ~/repos as the directory to contain my new project repository, and some generic project and package names -- please substitute the names you want for your own project, package, and directory).

# check to make sure you're using the latest version of Poetry
poetry self update
# change to the directory that will contain your new project
cd ~/repos
# create a new Poetry Python project
poetry new --src my_project --name my_package

Notes on your new Poetry project

  • Use the --src option to put your package code in a src subdirectory -- highly recommended!
  • Use the --name my_package option to give your package a different name than the project directory. Otherwise, skip this option to use the same name for your project and package directories.

Your new Poetry project directory

Depending on the project and package names you selected, your new Poetry project directory should look something like this:

my_project/
├── pyproject.toml
├── README.rst
├── src
│   └── my_package
│       └── __init__.py
└── tests
    ├── __init__.py
    └── test_my_package.py

Note that the README.rst file is completely empty (0 bytes) so if you'd prefer to write your README using Markdown, simply enter:

mv README.rst README.md

That's the easiest file conversion ever!

You can see what's in the pyproject.toml file like this:

cat pyproject.toml

Commit your new Python project to git

Now that Poetry has created your new project, commit it to git to track all the changes and additions from this point forward.

# make sure you're in the root of the new project directory 
# change the path for your specific project
cd ~/repos/my_project
# initialize the project directory as a git repo
git init
# (optional) change the name of your 'master' branch to 'main'
git branch -m main
# add all the files that Poetry just created
git add .
# commit the just-added files to the repo

Git will display output that lists all the files you've committed.

Add your new git repo to GitHub

Now that you've created a git repo, let's add it to the GitHub desktop software, and publish it to Github.

Add your new git repo to GitHub Desktop

GitHub Desktop lets you manage and sync your local repos with GitHub, but first GitHub Desktop needs to know about your local repos. To add your new repo to GitHub Desktop:

  1. Open GitHub Desktop on your development workstation.
  2. Log into GitHub, if required.
  3. Drag your new repo folder onto the box with the dotted line border that says: Pro Tip! You can drag & drop an existing repo..."
  4. In the Add local repository dialog box that appears, confirm you've selected the correct repo.
  5. If not, click the Choose... button. Otherwise, if everything looks good, click Add repository.

This will add your new repo to the GitHub Desktop, but it's not published yet. Note that you can also select a local repository to add from the GitHub Directory menu. Select Repository : Add Repository...

Publish your new repo to GitHub

Now that GitHub Desktop can manage your new repo, publish it to GitHub:

  1. Click the Publish repository button to confirm that you want to push your new repo to GitHub.

  2. In the Publish repository dialog box, confirm that the suggested repository Name is what you want, or edit it here.

  3. Add a short Description.

  4. Uncheck Keep this code private if you want to share your code with others. Note that you'll need to add a license file, too, if this is the case.

  5. Click Publish repository.

Review your new GitHub repo

Now that you've created a new repo on GitHub, login to GitHub using your favorite browser and take a look at the Code tab for your new repo. If you set your new repo up as public (not private), follow the steps in Adding a license to a repository - GitHub Docs to create, select, and commit a license file.

If you add a LICENSE file to your repo, use GitHub Desktop to pull it to your local clone: just click on the Fetch origin button in GitHub Desktop and follow the prompts to retrieve the new LICENSE file.

Now that you've created and configured your new repo on GitHub, you can use other development tools besides GitHub Desktop, like Visual Studio Code, to sync changes between your local clone and GitHub -- or you can still use the command line.

Update your Poetry project with packages

Now that you've created a new Python project with Poetry and added it to GitHub, you can also use Poetry to manage your project's package dependencies and the virtual development environment.

Once your project is set up with Poetry, it's easy to add additional packages. To add the pillow graphics manipulation package, for example, enter:

poetry add pillow

This will update the pyproject.toml file, and create a virtual environment, if required. In addition, the poetry add command will install any packages specified, and any dependencies.

If you have a situation where you depend on a specific version of a package to add another, poetry add will display a message telling you which version number you need to resolve the dependency issue. Simply edit the pyproject.toml file with the correct version number and run the poetry add command again.

Clone this wiki locally