Creating Packages

Last updated on 2026-07-14 | Edit this page

Overview

Questions

  • Where do I start if I want to make a Python package?
  • What will I need / want in my package?
  • What’s considered good practice with packaging?

Objectives

  • Create and build a basic example Python package
  • Understand all the parts and decisions in making the package

Introduction

This episode will see us creating our own Python project from scratch and installing it into a Python virtual environment ready for use. Feel free if you’re feeling adventurous to create your own package content or follow along with this example of a Fibonacci counter.

Fibonacci Counter

This package will allow a user to find any value from the Fibonacci sequence. The Fibonacci sequence is a series of whole numbers where each number is the sum of the two previous numbers. The first 8 numbers of the sequence are 0, 1, 1, 2, 3, 5, 8, 13.

Callout

Reinventing the wheel

It is good to ask yourself if the package or features you are designing have been done before. Obviously we have chosen a simple function as the focus of this episode is on packaging code rather than developing novel code.

Creating the package contents

In this section we will go through creating everything required for the package.

Challenge

What files and content go into a package?

Think back to the earlier episodes and try to recall all the things that can go into a package.

  1. Python Module - This is the directory with the Python code that does the work.
  2. Configuration File - e.g. your pyproject.toml file
  3. Other metadata files - e.g. LICENCE, README.md, citation.cff

In this episode we will only be creating a minimal example so many of the files you have thought of won’t be included. Next we will be creating our directory structure. In either your documents folder if you are on Windows or your home directory if you are on macOS or Linux, create a folder called fibonnaci_uos_name

📦 fibonacci_uos_name/
├── 📂 fibonacci_uos_name/
│   └── 📄 sequence.py
│   └── 📄 __init__.py
└── 📄 pyproject.toml

The first thing we will do in this project is create the Python module (the actual code!).

Discussion

Creating Python module

  1. Create a Python file called sequence.py as shown in the structure above.
  2. Add the following code which contains a function that returns the Fibonacci sequence

PYTHON 

def compute(n_terms):
  num1 = 0
  num2 = 1
  next_num = 1
  count = 0

  while count < n_terms:
    print(num1)
    count += 1
    num1, num2 = num2, next_num
    next_num = num1 + num2
Challenge

Using your Python module

With your Python environment activate, launch Python and test importing and using your package.

1. Navigate to a different directory to ensure you are importing the package not the local directory

BASH 

cd ../..

2. Launch Python and import package

BASH 

python

PYTHON 

from fibonacci_uos_name.sequence import compute

compute(5)

or

PYTHON 

import fibonacci_uos_name.sequence

fibonacci_uos_name.sequence.compute(5)

Configuration File

In this section we are going to look deeper into the pyproject.toml. Sections in a .toml file are called tables. In a pyproject.toml file there are 2 tables required for a minimum working pyproject.toml: a [build-system] table and a [project] table. Take a look at the minimum example pyproject.toml below.

TOML 


[build-system]
requires = ["setuptools"]


[project]
name = "fibonacci_uos_name"
version = "0.1.0"
description = "A package to calculate the fibonacci sequence"
dependencies = ["pandas", "numpy"]

[build-system]

The [build-system] table specifies information required to build your project directory into a package. The main key in this table is requires, this key states what build tool(s) should be used to do this building. There are multiple popular build tools that can be used to build your project, in this tutorial we will use setuptools, as it is simple and very popular.

[project]

The [project] table is where your package’s core metadata is declared.

Callout

pyproject.toml documentation

The full list of accepted keys can be found here in the documentation

Challenge

Create your configuration file

Create a pyproject.toml file with the two required tables. In the [project] table include the following keys:

  • name
  • version
  • description
  • authors
  • keywords

TOML 

[build-system]
requires = ["setuptools"]

[project]
name = "fibonacci_uos_name"
version = "0.1.0"
description = "A package which can produce the Fibonacci sequence"
authors = [{name = "your_name", email="youremail@email.com"}]
keywords = ["fibonacci", "maths"]

Running python -m pip install . will install your package. Just ensure your terminal’s working directory is the same as the pyproject.toml file!

Project & Packaging Naming

Referring back to the project structure:

📦 my_project/
├── 📂 my_package/
│   └── 📄 my_code.py
│   └── 📄 __init__.py
└── 📄 pyproject.toml

The name of your package directory is the name that users will import when they use the package

PYTHON 

from my_package.my_code import my_func

my_func()

PyPI which we looked at in the accessing packages episode and other tools like build which we cover later, use the project name specified in your pyproject.toml. It is common to keep these names consistent, so the package name the user installs is the same that is used to import the package.

Callout

Package Name Discrepency

Some packages do not use the same name, one famous example is pillow. The project name is pillow but the package you import inside is PIL.

BASH 

pip install pillow

PYTHON 

from PIL import Image
Callout

Editable Install

When installing your own package locally, there is an option called editable or -e for short. python -m pip install -e .

With a default installation (without -e), any changes to your source package will only appear in your Python environment when your package is rebuilt and reinstalled. The editable option allows for quick development of a package by removing that need to be reinstalled, for this reason it is sometimes called development mode!

Key Points
  • A package can be built with as little as 2 files, a Python script and a configuration file
  • pyproject.toml files have 2 key tables, [build-system] and [project]
  • Editable installs allow for quick and easy package development