Custodian Not Found: Troubleshooting and Setup for Cloud Custodian

Running into a “custodian not found” error is frustrating, especially when all you’re trying to do is automate some straightforward cloud governance. Cloud Custodian is a powerful Python tool for managing and enforcing policy in your cloud environments—including Microsoft Azure, AWS, and more. But installation hiccups, missing dependencies, or a simple stray typo can leave you dead in the water.

This guide cuts through confusion, showing you how to fix “custodian not found” errors, whether you’re working in your local terminal, a CI/CD pipeline, or even a container. And if you landed here by mistake because you’re chasing the Custodian from Remnant 2—don’t worry, we’ll help you spot the difference and get you back on the right path.

Whether you’re just getting started or running complex Microsoft environments with strict governance needs, this article has you covered with step-by-step troubleshooting, best practices, and links to governance strategies, like this one on Azure enterprise governance. Let’s solve those “not found” headaches and keep your cloud in check.

Understanding Custodian Not Found Errors in Cloud Custodian Setup

Let’s break down what’s really going on when you see “custodian not found” pop up in your terminal window. Nine times out of ten, this message means something simple: your system can’t locate the Custodian executable. That’s often because it’s not installed, the install didn’t go where you thought, or your command line isn’t looking in the right spot.

Common culprits for this error include missing prerequisites, mismatched Python versions, failing to activate a virtual environment, or a misconfigured PATH variable. Sometimes, even permissions issues or security policies—like AppLocker or SELinux—can block the tool without obvious warnings, making it seem like Custodian vanished into thin air.

If you’re working with cloud governance, especially across Microsoft or hybrid environments, you want dependable automation tools on your side. A “not found” error is often a sign your technical foundation needs attention, whether it’s dependency management, handling virtual environments, or correctly pulling Custodian in your deployments. You might even run into issues with CI/CD runners or when packaging Custodian into Docker containers for Kubernetes.

Before you jump into reinstalling or overhauling your setup, it’s good to understand what triggers these errors and familiarize yourself with the tools involved—like Python 3, pip, UV, and virtual environments. Up next, you’ll get step-by-step instructions for proper installation and tips on prepping your environment so that everything just works when you call the “custodian” command.

Installing Custodian with UV and Pip: Step-by-Step

1. Verify Python 3 Installation
2. Open your terminal and check if Python 3 is installed by running:

• python3 --version or python --version

1. If you don’t see version 3.x.x, install Python 3 first—don’t skip this step, or nothing else will work.
2. Install UV (Modern Python Installer)
3. UV is the next-gen replacement for pip and helps handle dependencies faster and more reliably. To install UV:

• With pip: pip install uv
• Alternatively, get pre-built binaries from the UV GitHub project.

1. Create and Activate a Virtual Environment (Recommended)
2. A virtual environment keeps your Python dependencies in one tidy, conflict-free folder. Run:

• python3 -m venv cenv
• Activate on macOS/Linux: source cenv/bin/activate
• Activate on Windows: cenv\Scripts\activate

1. Install Cloud Custodian
2. With your environment set, run:

• uv pip install c7n or, if using classic pip, pip install c7n

1. This command grabs Cloud Custodian and all required dependencies. Wait for the message saying install completed without errors.
2. Check the Installation
3. In your terminal, type:

• custodian version or custodian --help
• If you see output with the version or help text, you’re set. If the command isn’t found, review your virtual env activation or PATH.

1. Avoid Common Pitfalls
2. On Windows, make sure Scripts is in your path when the virtual environment is activated. On macOS/Linux, keep your terminal in the directory where you activated the environment.

Note: If “custodian” is still not recognized, try running python -m custodian to see if the module is properly installed but not on PATH. This helps diagnose binary path issues without reinstalling everything.

Setting Up Python 3 and Virtual Environments for Custodian Access

1. Install Python 3
2. Go to the official Python website to download the latest Python 3.x installer for your OS, or use a package manager (Homebrew, apt, or Windows Store). Make sure the install location is added to your PATH.
3. Confirm Python is on Your PATH
4. Open a new terminal window and type:

• python3 --version (macOS/Linux)
• python --version (Windows, or if python3 isn’t found)

1. If this returns an error, double-check that Python is actually installed and recognized in your system’s path.
2. Create a Virtual Environment
3. Use the built-in venv module for isolation:

• python3 -m venv myenv

1. This creates a folder named “myenv” that holds your project-specific dependencies.
2. Activate the Virtual Environment

• On macOS/Linux: source myenv/bin/activate
• On Windows: myenv\Scripts\activate

1. Your terminal prompt should change, showing you’re inside the Python environment.
2. Verify Activation and Install Custodian
3. While the environment is activated, install Cloud Custodian with pip install c7n or uv pip install c7n. Always activate the environment before working with Custodian, or else you risk installing to—or running from—the wrong location.
4. Avoiding Environment Mix-ups
5. If you use Conda, make sure to activate the Conda environment before installing. To check where “custodian” will run from, use which custodian (macOS/Linux) or where custodian (Windows), or try python -m custodian for another quick test.

Proper Python 3 and virtual environment setup is the foundation for making sure “custodian” runs every time. Skipping or mixing these steps is the single biggest reason for those annoying “not found” errors, even if you think everything’s installed right.

Installing Prerequisites on macOS, Windows, and Linux

• macOSInstall Homebrew if you haven’t already: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
• Use Homebrew to install Python 3: brew install python
• Check installation: python3 --version
• Install virtualenv (optional but helpful): pip3 install virtualenv
• WindowsDownload Python from the official site or install via Microsoft Store for simpler setup.
• Make sure to “Add Python to PATH” during install—don’t uncheck this!
• Check install: python --version
• Install virtualenv if needed: pip install virtualenv
• Optional: Use Chocolatey for package management: choco install python
• Linux (Ubuntu/Debian/Fedora/RedHat/CentOS)Ubuntu/Debian: sudo apt update && sudo apt install python3 python3-venv python3-pip
• Fedora/RedHat: sudo dnf install python3 python3-venv python3-pip
• CentOS: sudo yum install python3 python3-venv python3-pip
• Check version: python3 --version

After Python is set up, verify the versions and ensure pip is available. Install UV for faster dependency handling with pip install uv if desired. Setting up these basics will save you countless headaches down the road, especially in enterprise or regulated environments with strict requirements. Once you’re all set, you’re ready to move on to actual Custodian installation.

Developer Installation with Technical Setup and Repository Cloning

If you’re ready to dive in as a Cloud Custodian developer or you want to run the bleeding edge version, this section shows you the right setup. Unlike a simple install, you’ll be grabbing the source code, which gives you full access to contribute, run tests, or tweak policies directly.

Working from source means you’ll be cloning the official Cloud Custodian repository and handling your environment with a little more care. Sometimes, you’ll run into technical bits like managing unique user identifiers (UID/UUID) or dealing with user permissions. It’s important to keep your dev environment isolated to prevent accidental issues affecting your main machine.

This overview covers the reasoning and core process. Next, you’ll get clear guidance on activating the repository’s environment, running the test suite, and making sure Custodian runs locally as expected. Whether you’re contributing code, checking out a feature branch, or validating a bug fix, the upcoming steps outline how to get started smoothly—no headaches, no loose ends.

Running Tests and Executing Custodian in UV Environment

1. Activate Your Development Environment
2. Enter the repository directory and activate your virtual environment with source venv/bin/activate (Linux/macOS) or venv\Scripts\activate (Windows).
3. Install Required Dependencies
4. Use UV to install test dependencies: uv pip install -e .[dev,test] in the Cloud Custodian folder.
5. Run the Test Suite
6. uv run pytest will execute all automated tests, showing you any failures or issues. This checks that your developer install is working.
7. Execute Custodian Locally
8. Run uv run custodian version or uv run custodian --help to verify Custodian is unlocked, the user interface appears as expected, and everything is operational.

If you hit strange errors or missing commands, double-check your virtual environment activation and package install step. Most issues are fixed by repeating those commands in the right directory.

Troubleshooting Path and Binary Issues for Custodian Not Found

1. Check if Custodian is on Your PATH
2. Run which custodian (macOS/Linux) or where custodian (Windows) to see if the binary is accessible. If nothing appears, the tool isn’t on your path.
3. Activate the Right Virtual Environment
4. Make sure you’ve activated the environment where Custodian was installed. The prompt should usually change to show you’re in the environment (e.g., (cenv)).
5. Directly Run the Module as a Diagnostic
6. Try python -m custodian. If this works but “custodian” does not, it’s a sign your scripts directory isn’t in the system PATH.
7. Edit Your PATH Variable
8. For macOS/Linux: check ~/.bashrc, ~/.zshrc, or ~/.profile and add the location of your Python scripts (usually ~/.local/bin or your venv’s bin directory) if needed.
9. For Windows: check that Scripts in your virtual environment is added to your system’s PATH if running outside the activated environment.
10. Watch for User Context and Permissions
11. Running as sudo or a different user can change what’s on your PATH. Security policies or restricted shells may block binary execution or even hide installed scripts (enterprise tools like AppLocker/SELinux can especially cause this).
12. Check in CI/CD and Container Environments
13. In GitHub Actions, GitLab CI, or Jenkins, ensure the “custodian” binary is installed within the runner or image. In Docker, add the install to your Dockerfile and set correct ENTRYPOINT or PATH so that “custodian” is available when the container runs.

By following these steps, you can quickly identify whether it’s a path issue, a permission glitch, or a missing install causing the “not found” headache. Diagnosing with which, python -m, and understanding user environments is key to unlocking a working Custodian setup across all platforms.

Avoiding Custodian Remnant Wiki Confusion: Cloud Custodian vs. Remnant 2

Let’s clear the air: Cloud Custodian is a cloud governance tool for automating security and compliance controls. It has nothing to do with “The Custodian,” a character you meet in the action game Remnant 2. If you’re looking for RPG quest tips or boss strategies, you’ll want the gaming wikis, not this technical guide.

Search overlap happens because the word “custodian” pops up in both tech and gaming circles. When troubleshooting cloud automation errors, check for context clues like “Python,” “pip install,” or “command not found”—all signs you’re in the right place for IT solutions, not a game walkthrough. Stick with this guide if you’re after real-world cloud policy enforcement, especially for Microsoft and multi-cloud environments.