# Quickstart for Chainguard Libraries

URL: https://chainguard-docs-preview-git-uv-frozen-installs.chainguard.app/chainguard/libraries/introduction/quickstart.md
Last Modified: October 16, 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](/chainguard/libraries/introduction/overview/#upstream-fallback-and-controls),
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](/chainguard/libraries/java/migration/)
* [JavaScript migration guide](/chainguard/libraries/javascript/migration/)
* [Python migration guide](/chainguard/libraries/python/migration/)

## Prerequisites

Before getting started:

* If you're not yet a Chainguard user, you must [create an
      account](https://console.chainguard.dev/auth/login).
* Ensure your organization is entitled to Chainguard Libraries. To add an
  entitlement for an ecosystem, contact your Chainguard account team.

Chainguard Libraries are available to Catalog Starter and Free tier users, and trial users.

## Step 1: Choose your access method

There are two ways to access Chainguard Libraries: using an [artifact manager](#artifact-manager) or [direct access](#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](/chainguard/libraries/java/global-configuration/),
[JavaScript](/chainguard/libraries/javascript/global-configuration/), and
[Python](/chainguard/libraries/python/global-configuration/).

### 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](/chainguard/libraries/java/build-configuration/),
[JavaScript](/chainguard/libraries/javascript/build-configuration/), and
[Python](/chainguard/libraries/python/build-configuration/).

## Step 2: Create a pull token

[Pull tokens](/chainguard/libraries/introduction/access/#creating-pull-tokens-for-libraries)
are required for authentication.

You can [create pull tokens via the Chainguard
Console](/chainguard/libraries/introduction/access/#creating-pull-tokens-with-the-chainguard-console)
under **Overview > Manage pull tokens > Create access token**.

You can also [create one using `chainctl`](/platform/chainctl/chainctl-docs/chainctl_auth_pull-token_create/):



**Java**



```bash
chainctl auth pull-token create --repository=java --ttl=720h
```




**JavaScript**



```bash
chainctl auth pull-token create --repository=javascript --ttl=720h
```




**Python**



```bash
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.

Learn more about pull tokens, and using environment variables for pull token credentials, in the [Libraries access documentation](/chainguard/libraries/introduction/access/).

## 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](/chainguard/libraries/introduction/overview/#upstream-fallback-and-controls), 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**



### Java

* [Repository manager](/chainguard/libraries/java/global-configuration/): Configure your repository manager or build tool to use
  `https://libraries.cgr.dev/java/` as the first repository for artifact
  resolution.
* [Direct access](/chainguard/libraries/java/build-configuration/): 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](/chainguard/libraries/java/build-configuration/#minimal-example-project)
and
[Gradle](/chainguard/libraries/java/build-configuration/#minimal-example-project-1) to understand how to use these repositories.




**JavaScript**



### JavaScript

* [Repository
  manager](/chainguard/libraries/javascript/global-configuration/): 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](/chainguard/libraries/javascript/build-configuration/): Configure your `.npmrc` to use `https://libraries.cgr.dev/javascript/` as the registry. You can do this automatically with [the `chainctl auth configure-npm` command](/chainguard/libraries/javascript/migration/#direct-access).

Check out minimal example projects for
[npm](/chainguard/libraries/javascript/build-configuration/#minimal-example-project),
[pnpm](/chainguard/libraries/javascript/build-configuration/#minimal-example-project-1),
[Yarn](/chainguard/libraries/javascript/build-configuration/#minimal-example-project-2),
[Yarn
Classic](/chainguard/libraries/javascript/build-configuration/#minimal-example-project-3),
and
[Bun](/chainguard/libraries/javascript/build-configuration/#minimal-example-project-4) 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](/chainguard/libraries/javascript/build-configuration/#update-hashes-auth)
> build configuration page.




**Python**



### Python

* [Repository manager](/chainguard/libraries/python/global-configuration/): Add Chainguard Libraries as a remote repository in your
  repository manager.
* [Direct access](/chainguard/libraries/python/build-configuration/): 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](/chainguard/libraries/policies-and-security/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](/chainguard/libraries/python/build-configuration/#uv-minimal) and [pip](/chainguard/libraries/python/build-configuration/#pip-minimal) 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](/chainguard/libraries/python/build-configuration/#update-hashes-auth).







<a id="upstream-note"></a>

> **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](/chainguard/libraries/introduction/overview/#upstream-fallback-and-controls).

## Step 4: Verify your libraries

After setup, you can verify which dependencies were built from source by Chainguard. This step requires [`chainctl`](/platform/chainctl-usage/how-to-install-chainctl/); if you entitled access through the Chainguard Console, install `chainctl` and log in with `chainctl auth login` before continuing.

```bash
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.

For JavaScript projects, you can also verify a lockfile directly, without installing dependencies. For example: `chainctl libraries verify package-lock.json`.

Learn more in [Chainguard Libraries verification](/chainguard/libraries/policies-and-security/verification/).

## FAQs

Refer to the [Chainguard Libraries FAQ page](/chainguard/libraries/troubleshooting/faq/) for common questions and issues.