# Quickstart for Chainguard Libraries

URL: https://deploy-preview-3741--ornate-narwhal-088216.netlify.app/chainguard/libraries/quickstart.md
Last Modified: August 7, 2026
Tags: Chainguard Libraries

Learn how to get started with Chainguard Libraries

Most supply chain attacks succeed the same way: malicious code is injected into a package after the source is written — either as a backdoored binary with no verifiable source, or as a malicious install-time script that runs the moment a dependency is pulled. Recent attacks on LiteLLM, Telnyx, and Axios all followed this pattern.
Chainguard Libraries for Java, JavaScript, and Python are rebuilt from verified source in an isolated build environment, making them malware-resistant by design. When a package is available as a Chainguard-built library, that rebuilt package is served first. When you use the upstream fallback, the same ecosystem endpoint can also serve eligible upstream packages that Chainguard has not yet built, subject to configurable policy controls such as cooldown and malware scanning. This gives your engineers drop-in replacements for the packages they already use, with no breaking changes.
This guide covers the high-level steps to get up and running with Chainguard Libraries. For full reference documentation on any step, follow the links provided throughout this page. For ecosystem-specific guides, refer to the following pages:
Java migration guide JavaScript migration guide Python migration guide Prerequisites Before getting started:
If you’re not yet a Chainguard user, you must create an account.
Install chainctl and log in:
chainctl auth login Entitle access for yourself to Chainguard Libraries.
Chainguard Libraries are available to Catalog Starter and Free tier users, and trial users. Run the following chainctl libraries command to create an entitlement for libraries: chainctl libraries entitlements create --ecosystems=JAVASCRIPTThe available ecosystems are JAVA, JAVASCRIPT, and PYTHON.
Alternatively, you can create an entitlement and pull token in the Chainguard Console: while viewing a library ecosystem page, follow the prompts to create an access token.
Step 1: Choose your access method There are two ways to access Chainguard Libraries: using an artifact manager or direct access.
Artifact manager Configure credentials once in a tool like JFrog Artifactory, Sonatype Nexus, or Cloudsmith. This centralizes policy, logging, and fallback behavior, and is the safest approach for organizations with multiple teams and applications.
Learn how to configure a repository manager in the global configuration documentation for Java, JavaScript, and Python.
Direct access Configure authentication directly in each project’s build configuration.
This option is faster to set up initially, but requires per-project and per-workstation configuration. This increases the risk of credentials being committed to source control or going stale.
Learn how to set up direct access in the build configuration documentation for Java, JavaScript, and Python.
Step 2: Create a pull token Pull tokens are required for authentication. You can create one using chainctl:
chainctl auth pull-token create --repository=java --ttl=720h chainctl auth pull-token create --repository=javascript --ttl=720h chainctl auth pull-token create --repository=python --ttl=720h The default TTL is 720h (30 days); the maximum is 8760h (365 days).
The command returns a username and password for basic authentication. Store these securely, as they won’t be shown again.
You can also create pull tokens via the Chainguard Console under Overview > Manage pull tokens > Create access token.
Learn more about pull tokens, and using environment variables for pull token credentials, in the Libraries Access documentation.
Step 3: Configure your build tools Once you have a pull token, you can configure your build tool. Configuration steps vary by build tool and ecosystem. Refer to the ecosystem-specific documentation pages for instructions.
If you configure upstream fallback, the same ecosystem endpoint can serve both:
Libraries rebuilt from source by Chainguard, and Eligible packages from the upstream public registry when Chainguard has not built that package or version yet Upstream packages served through the Chainguard Repository are subject to configurable policy controls such as cooldown and malware protection. It is strongly recommended that you follow this approach.
Java Repository manager: Configure your repository manager or build tool to use https://libraries.cgr.dev/java/ as the first repository for artifact resolution. Direct access: Configure your tool to retrieve artifacts directly from the Chainguard Libraries for Java repository at https://libraries.cgr.dev/java/. Use direct access for small teams or evaluations, or when you have an existing repository configuration you can’t change yet. In addition to malware-resistance, Chainguard Libraries for Java includes CVE remediation for select libraries. These patched versions help reduce known risk while you plan your next major version upgrade. You can view which libraries have CVE remediation available in the Chainguard Console.
Check out minimal example projects for Maven and Gradle to understand how to use these repositories.
JavaScript Repository manager: Add the Chainguard Libraries registry as a remote repository and configure it as the first choice for package resolution, with npm as a fallback only where necessary. Direct access: Configure your .npmrc to use https://libraries.cgr.dev/javascript/ as the registry. Check out minimal example projects for npm, pnpm, Yarn, Yarn Classic, and Bun to understand how to use these repositories.
Migrating an existing JavaScript project? If you have an existing lockfile with upstream hashes, use chainctl libraries update-hashes to update checksums to Chainguard’s automatically, without regenerating your lockfile from scratch. The command authenticates to Chainguard Libraries; see the authentication options in the JavaScript build configuration page.
Python Repository manager: Add Chainguard Libraries as a remote repository in your repository manager. Direct access: Configure your tool to retrieve artifacts directly from the Chainguard Libraries for Python. Note that there are multiple repositories:
https://libraries.cgr.dev/python/ with the simple index at https://libraries.cgr.dev/python/simple https://libraries.cgr.dev/python-remediated with the simple index at https://libraries.cgr.dev/python-remediated/simple for libraries with CVE remediation In addition to malware-resistance, Chainguard Libraries for Python includes CVE remediation for select libraries. These patched versions help reduce known risk while you plan your next major version upgrade. You can view which libraries have CVE remediation available in the Chainguard Console.
Check out minimal example projects for uv and pip to understand how to use these repositories.
Migrating an existing Python project? If you have an existing lockfile with upstream hashes, use chainctl libraries update-hashes to update checksums to Chainguard’s automatically, without regenerating your lockfile from scratch. The command authenticates to Chainguard Libraries; see the authentication options in the Python build configuration page.
Note on upstream fallback: The upstream fallback is available as an opt-in setting for both repository manager or direct access approaches, and is turned off by default. Learn more about upstream fallback policy and controls in the Libraries overview.
Step 4: Verify your libraries After setup, you can verify which dependencies were built from source by Chainguard:
chainctl libraries verify /path/to/artifact Note: Running chainctl libraries verify requires one of the libraries.java.pull, libraries.javascript.pull, or libraries.python.pull permissions, or the Owner role.
Learn more in Chainguard Libraries verification.
FAQs Refer to the Chainguard Libraries FAQ page for common questions and issues.