Related Projects

Satellite apps

We use the term "satellite apps" to refer to other CFPB-maintained Python source code repositories and packages that provide functionality or content for but are not included in Most but not all of these repositories can be run or tested without needing to set up the full website.

We have six satellite apps that are maintained outside of the codebase:

These satellite apps are imported into as part of the project requirements files.

Thinking about making a new satellite app?

Satellite apps were originally built to be imported into the website before we started using Wagtail to manage site content. We now prefer to build projects as apps inside the repo. For more info, refer to the "Setting up new project code for" page on the CFGOV/platform wiki on GHE.

Other Python packages

CFPB also develops and maintains several other Python source code repositories and packages that are used on but are more general-purpose.

These include:

The cfpb/development repository contains the CFPB development guidelines used on these projects.

Developing Python packages with

Developers working on changes to satellite apps or other Python packages often want or need to test their work as part of the larger project.

The standard installation process for includes whatever versions of these packages are specified in project requirements files. Developers may want to temporarily or permanently replace those with a local copy of package source code.

Using a local virtual environment

When running in a virtual environment local to your developer machine, standard usage of pip install can be used to swap out package versions.

Running pip install -e path/to/local/repo will install local source code in "editable" mode, replacing the satellite app version installed from requirements files with your local copy:


The retirement app used in this example is deprecated and is shown for illustration purpooses only.

# In a local virtual environment, after installing
# Python packages have been installed from requirements files.
# This includes, for example, the retirement satellite app:
( $ pip freeze | grep retirement

# Replace this version with an editable install pointing to your local copy.
( $ pip install -e ../retirement/
Installing collected packages: retirement
  Found existing installation: retirement 0.10.0
    Uninstalling retirement-0.10.0:
      Successfully uninstalled retirement-0.10.0
  Running develop for retirement
Successfully installed retirement

# The Python environment is now using the local copy.
( $ pip freeze | grep retirement

Installing a local copy of source code in editable mode ensures that any changes made to files there will take effect immediately.

To switch back to the default version of a Python package, removing the use of a local copy, you can manually install the version specified in the requirements files:

( $ pip install retirement==0.10.0

Re-running the full virtual environment setup script will do the same thing.

Using Docker

Working on Python packages requires a different approach when running locally with its Docker setup. This is because while your local directory is exposed to the container, sibling directories or other locations where you might clone other repositories are not.

For this reason, the Docker setup provides the ability to use the local subdirectory as place to put local copies of Python packages.

Any packages put there (e.g. via a git clone of a satellite apps' repo) will be automatically added to the PYTHONPATH in the Python containers. Apps located within will be importable from Python running in the Docker containers, and will take precedence over any versions installed from requirements files as part of the Docker images.

To switch back to the default version of a Python package, removing the use of a local copy, simply delete the copy from the develop-apps directory.

For any satellite apps that provide front-end assets that need to be built, you will need to run that step seperately:

# Check out the retirement satellite app into develop-apps:
cd develop-apps
git clone

# Build the front-end:
cd retirement

If the satellite app needs any Python requirements that are not specified in the requirements, they will need to be installed seperately by accessing the Python container shell and using pip:

docker-compose exec python sh
pip install [PACKAGE NAME]