Installation

🚀Install Custy

Python 3.14+

Choose a supported native installation method, prepare its requirements, and verify the Custy CLI.

Commandpython -m pip install --index-url $PRIVATE_INDEX_URL custy==2.1.2

📦Category

Getting Started

🚀Quick Command

python -m pip install [OPTIONS] SOURCE

---

private GitLab PyPIsource checkoutrelease assetsdeveloper setup

---

📌

Native Python

3.14 or newer

🌿

Core System Tool

Git

📁

Recommended Isolation

Virtual environment

📦

Private Registry

GitLab PyPI

🐳

Container Alternative

Local Docker build

Overview

Custy can be installed from the project's private GitLab PyPI registry, a source checkout, a Python artifact attached to a release, or the Git repository itself. Contributors should use an editable installation with the development dependency group. Docker is a separate alternative when you do not want to install Python or Git directly on the host.

ℹ️Private registry, not public PyPI

pip install custy without an index configuration does not resolve this project from public PyPI. Authorized users can select the private GitLab index; source checkouts, release artifacts, and reviewed Git revisions remain supported alternatives.

---

Requirements

The required host tools depend on whether Custy runs natively or inside Docker.

📌Requirements

Python 3.14+

Required

Required for native installation. This is the minimum version declared by the current package metadata.

pip

Required

Required for native installation. Invoke it through the selected Python interpreter.

Git

Required

Required on the native host for Custy's repository, version, changelog, commit, tag, push, and pipeline operations.

Virtual Environment

Recommended

Keep Custy and its dependencies isolated from the system Python and unrelated projects.

Docker

Optional

Use the container path instead of installing Python, pip, or Git on the host.

Make

Optional

Use repository Make targets as development and container helpers; Make is not required by the Custy CLI itself.

---

Feature-Specific Tools

✨Install Only When Needed

🌿Commitizen

Install custy[commitizen] when using Commitizen versioning or commit-message validation. It remains optional for normal Custy workflows and is included in the production Docker image.

✅Pre-Commit Hooks

Install custy[hooks] when local Custy must execute pre-commit-managed hooks directly. Projects without pre-commit do not need this extra. The production image includes it.

📄Interactive Editor

Install at least one configured editor for commit, tag, or release message review. Windows defaults to VS Code then Notepad; Docker includes Micro, Nano, Vim, and Vi.

🛡️Remote Credentials

Configure SSH or supported Git credentials outside Custy before a push operation communicates with a remote.

🐳Docker Compose

Install the Compose plugin only when using the repository's development or production Compose services.

---

Choose an Installation Method

✨Native Installation Choices

📦Private GitLab PyPI

Recommended for authorized users who want an immutable, reviewed package without maintaining a source checkout.

📁Source Checkout

Recommended when you want to inspect the exact source and install a normal runtime copy.

📦Release Artifact

Install a wheel or source distribution attached to a reviewed release when that release provides one.

🌿Git Revision

Install directly from a reviewed tag or commit without keeping a separate checkout.

🚀Editable Contributor Setup

Install the source tree in editable mode with testing, linting, formatting, packaging, and Git-hook tools.

---

Method 1: Install from Private GitLab PyPI

Ask a project maintainer for the GitLab project ID and a deploy token limited to read_package_registry. Then install one exact package version in an isolated environment.

Install from the private project registry

bash

python -m venv venv

# Activate the environment, then install one reviewed version.

python -m pip install --index-url "https://<deploy-user>:<deploy-token>@gitlab.com/api/v4/projects/<project-id>/packages/pypi/simple" "custy==2.1.2"

custy --version

The Git release tag remains SemVer, while package metadata is canonical PEP 440. For example, tag v2.1.0-rc.1 is installed as custy==2.1.0rc1.

⚠️Keep registry credentials outside the repository

Do not commit deploy tokens, credential-bearing index URLs, or pip configuration containing secrets. Avoid --extra-index-url for private packages because competing indexes can create dependency-confusion risk. For strictly private dependency resolution, project maintainers should also review GitLab package-forwarding settings.

---

Method 2: Install from a Source Checkout

Clone the repository, create a virtual environment, and install the runtime package. This is the recommended native path when no reviewed release artifact has been selected.

Clone and create the environment

bash

git clone https://github.com/devalltect00/Custy.git
cd Custy
python -m venv venv

Activate the environment for your shell.

Windows PowerShell

powershell

venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install .

Linux or macOS

bash

source venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

---

Method 3: Install a Release Artifact

Custy's release workflow is configured to attach a Python wheel and source distribution. Open the Custy Releases page, choose a reviewed release, and confirm that the selected release actually contains the artifact before downloading it.

Install a downloaded wheel

bash

python -m pip install ./custy-<version>-py3-none-any.whl

Install a downloaded source distribution

bash

python -m pip install ./custy-<version>.tar.gz

⚠️Do not pin documentation to one old release

Artifact availability and version numbers change over time. Use the general Releases page, select the intended version deliberately, and verify the asset name shown by that release.

---

Method 4: Install Directly from Git

When you do not need a local checkout, pip can install a reviewed Git tag or commit into the active environment.

Install a reviewed revision

bash

# Replace <tag-or-commit> with the exact revision you reviewed
python -m pip install "git+https://github.com/devalltect00/Custy.git@<tag-or-commit>"

Omitting @<tag-or-commit> follows the repository's default branch and is less reproducible.

---

Editable Developer Installation

Contributors working on Custy itself should install the source tree in editable mode with the development dependencies declared in pyproject.toml.

Editable install with development tools

bash

python -m pip install -e ".[dev]"

Use python -m pip install -e . only when you need editable runtime code without the optional development tools. Add docs when working on Custy's legacy MkDocs sources: python -m pip install -e ".[dev,docs]".

💡Why use python -m pip?

Calling pip through python -m pip ensures that installation uses the Python interpreter from the active virtual environment.

---

Optional Makefile Helpers

The repository Makefile can create the standard venv/ environment and run the editable installation targets. These helpers are intended for a Custy source checkout and require GNU Make.

Contributor setup with Make

bash

make venv
make upgrade-pip
make install-dev

• make install installs editable runtime dependencies.
• make install-dev adds the development dependency group.
• make install-all adds both development and legacy documentation tools.
• Make is only a convenience layer; the equivalent python -m pip commands remain valid without it.

---

Verify the Installation

📌Installation Check

• The intended environment is activeRequired

  Your shell resolves Python and Custy from the selected virtual environment or installation.

• The Python version is compatibleRequired

  python --version reports Python 3.14 or newer for native use.

• The installed version is visibleRequired

  custy --version prints package version information.

• Command help rendersRequired

  custy --help shows the public commands and global options.

Verify the CLI

bash

python --version
git --version
custy --version
custy --help

From a source checkout, python -m app --help is an alternative module entry point when you need to distinguish a PATH problem from an application problem.

---

Common Installation Problems

⚠️Python version is too old

If pip reports an incompatible Python version, install Python 3.14 or newer, recreate the virtual environment with that interpreter, and install again.

⚠️custy is not recognized

Confirm that the intended virtual environment is active. You can also invoke its executable directly, such as venv\Scripts\custy.exe --help on Windows, or use python -m app --help from the source checkout.

⚠️Git command is unavailable

Install Git and make sure git --version works in the same shell. A successful Python package installation alone does not provide the Git executable required by Custy's main workflows.

---

Continue

🚀Related Commands

Commands commonly used together with this command.

Docker Setup

Build a self-contained Custy image with Python, Git, pip, and Make included.

Quick Start

Initialize and validate an existing repository.

Developer Setup

Prepare and verify an editable contributor environment.

custy init

Generate project-specific Custy resources.

custy validate

Check project readiness before a pipeline.