Getting Started

Getting Started#

This project is, first and foremost, a Copier template. What makes it nicer to consume is that it is also published as a Python package with a tiny wrapper CLI:

uvx python-package-copier-template [PATH_TO_PROJECT]

That wrapper exists so you do not need to remember the copier copy and copier update incantations every time. It checks the destination directory:

  • If there is no .copier-answers.yml or .copier-answers.yaml, it creates a project.

  • If there is a Copier answers file, it updates the project in place.

The version-resolution details for the wrapper live in CLI Reference.

You can inspect the published wrapper version with:

uvx python-package-copier-template --version

If you want to use the latest development version from GitHub instead of the latest published release:

uvx git+https://github.com/mgaitan/python-package-copier-template [PATH_TO_PROJECT]

And to inspect that development wrapper version:

uvx git+https://github.com/mgaitan/python-package-copier-template -- --version

Create a new project with the wrapper#

The most convenient path is:

uvx python-package-copier-template /path/to/your/new/project

That will run Copier in copy mode with sensible defaults and prompt you for the remaining project metadata.

The capture below shows a real wrapper-driven project creation during the docs build. Under the hood it runs non-interactively with defaults in a temporary directory, while displaying the normal command a user would type:

$ uvx python-package-copier-template [PATH_TO_PROJECT] Copying from template version 0.4.3.post5.dev0+3d0ee32     create  AGENTS.md     create  .copier-answers.yml     create  CONTRIBUTING.md     create  .github     create  .github/FUNDING.yml     create  .github/workflows     create  .github/workflows/cd.yml     create  .github/workflows/ci.yml     create  .github/workflows/template-update.yml     create  README.md     create  LICENSE     create  .gitignore     create  CODE_OF_CONDUCT.md     create  tests     create  tests/conftest.py     create  tests/test_cli.py     create  Makefile     create  pyproject.toml     create  src     create  src/demo_project     create  src/demo_project/__main__.py     create  src/demo_project/py.typed     create  src/demo_project/__init__.py     create  docs     create  docs/CONTRIBUTING.md     create  docs/conf.py     create  docs/_static     create  docs/_static/.gitkeep     create  docs/CODE_OF_CONDUCT.md     create  docs/index.md     create  docs/about_the_docs.md     create  docs/configuration.md     create  docs/getting_started.md     create  docs/development_workflow.md

After generation:

cd /path/to/your/new/project
uv sync
make qa
make test
make docs

That gives you a ready-to-work baseline with dependencies, QA, tests, and documentation. Use make docs-open if you want to open the generated HTML locally.

Update an existing project with the wrapper#

For a project already created from this template, run the same wrapper from inside the repository:

cd /path/to/existing/project
uvx python-package-copier-template .

Because the project contains .copier-answers.yml, the wrapper switches to update mode automatically. The update process uses Copier metadata from that file to track the source template and the version previously applied.

Generated projects also include a scheduled template-update.yml workflow that can open a PR with template refreshes. That is useful for gradual adoption, but the local wrapper command is still the primary manual update path.

Use Copier directly#

If you prefer to avoid the wrapper, the equivalent explicit commands are:

Create a new project:

uvx --with=copier-template-extensions copier copy --trust "gh:mgaitan/python-package-copier-template" /path/to/your/new/project

Update an existing project:

cd /path/to/existing/project
uvx --with=copier-template-extensions copier update --trust .

This repository uses a couple of Jinja extensions, so copier-template-extensions must be available when you run Copier directly. The wrapper handles that for you, which is the main reason it exists.

Work against the local repository#

If you are developing the template itself and want to test the current checkout instead of a published release:

uv sync
uv run copier copy --trust --vcs-ref=HEAD . /path/to/your/test/project

That uses the local repository as the template source and resolves updates against the current HEAD.

GitHub and publishing notes#

If you choose GitHub repository creation during the questionnaire and have gh available, the template can bootstrap the repository for you. For public repositories, it also tries to enable GitHub Pages so the generated docs workflow can publish without extra manual setup.

For PyPI publishing in generated projects, the release workflow is based on Trusted Publishing. That still requires one manual registration step in PyPI for the project and workflow identity.

Contents