Improve error message and auto-detect subdirectories when template contains multiple templates in directories

Author: DhruvaKashyapCreated Feb 6, 2026Updated Mar 17, 2026

Thanks for this great tool!

I ran into a confusing case when working with a repository that contains multiple templates stored in subdirectories.

If I forget that the repo is structured that way and run:

bash
cookiecutter simple_cookiecutter

I get the following error:

A valid repository for "simple_cookiecutter" could not be found in the following locations:
simple_cookiecutter
~/.cookiecutters/simple_cookiecutter

At first, it looks like the repo can’t be found or cloned, but the real issue is that the repository exists, and I forgot to add --directory.

Suggested improvements:

Would it be possible to:

  1. Scan one directory level deep when the top-level repo is not a valid template, and list the available subdirectories that are valid templates, and/or prompt the user to choose one interactively.

  2. Improve the error message to say something like:

The repository was found, but no template was detected at the root.
Available subdirectories:
template_a
template_b
You may want to use --directory.
  1. Offer an interactive selection when multiple valid subdirectories are detected. This would make the error much clearer when working with multi-template repos

If this sounds reasonable, I’d be happy to contribute a PR Just let me know if there’s a preferred direction for the implementation.

Thanks!


Reproduce error

Here is a simple reproducible example. Consider the following folder:

simple_cookiecutter
├── d1
│   ├── cookiecutter.json
│   └── {{cookiecutter.project_slug}}
│       └── README.md
└── d2
    ├── cookiecutter.json
    └── {{cookiecutter.project_slug}}
        └── README.md

where simple_cookiecutter/d1/cookiecutter.json:

json
{
  "project_name": "project_d1",
  "project_slug": "{{ cookiecutter.project_name.lower().replace(' ', '_').replace('-', '_') }}"
}

simple_cookiecutter/d2/cookiecutter.json:

json
{
  "project_name": "project_d2",
  "project_slug": "{{ cookiecutter.project_name.lower().replace(' ', '_').replace('-', '_') }}"
}

simple_cookiecutter/d1/{{cookiecutter.project_slug}}/README.md

# {{cookiecutter.project_name}}

---

Welcome to D1: {{cookiecutter.project_name}}

simple_cookiecutter/d2/{{cookiecutter.project_slug}}/README.md

# {{cookiecutter.project_name}}

---

Hello D2: {{cookiecutter.project_name}}!

Source: cookiecutter/cookiecutter