Databricks Apps Can Use Workspace-Level Python and npm Repositories

If you have built an application with Databricks Apps, you probably know that managing dependencies can take more effort than expected. A Python app might need packages from a private PyPI repository, while its React frontend depends on JavaScript packages hosted in a private npm registry. When every app has to configure these repositories separately, the same settings get copied across projects, and maintaining them becomes a job of its own.

Databricks now lets workspace administrators configure default Python and npm package repositories for Databricks Apps. Apps in the workspace inherit these settings when they are built and deployed, while developers can still override the defaults for individual apps.

The feature became generally available on October 14, 2026. It gives organizations a central place to manage package sources, including private repositories that require authentication.

For development teams, the main benefit is simpler dependency management. Developers can keep package declarations in their projects, while administrators manage the repositories from which those packages are downloaded.

What Are Workspace-Level Package Repositories?

A package repository stores software libraries that applications can install. Python developers commonly use PyPI or a private Python package index. JavaScript developers use npm registries to install packages such as React, Express, and Vite.

Many organizations maintain private repositories to control which packages developers can use. These repositories may contain internal libraries, approved third-party packages, or versions that have passed the organization's security checks.

Before workspace-level defaults, developers often had to configure repository URLs in each app. A team might repeat the same Python index URL across several app.yaml files or maintain separate npm configuration files for multiple frontend projects.

Databricks can now apply the workspace's default repository settings when an app is built.

Here is how the responsibility is divided:

Responsibility	Workspace administrator	App developer
Choose the default Python repository	Yes	No
Configure the default npm registry	Yes	No
Manage repository credentials	Yes	No, unless an app-specific repository is required
Declare Python dependencies	No	Yes
Declare JavaScript dependencies	No	Yes
Override the workspace repository for one app	Controls the default	Yes, where supported
Test package compatibility	Provides repository controls	Yes

This setup keeps repository administration separate from application development. It also reduces the chance that different teams will accidentally use different package sources.

How the Feature Works

Databricks Apps installs dependencies during the app build process. The workspace repository settings tell the build process where to look for packages.

Python applications

For apps using pip, Databricks can provide workspace-level settings through environment variables such as:

PIP_INDEX_URL for the primary Python package index.
PIP_EXTRA_INDEX_URL for additional package indexes.
PIP_CERT for a custom certificate.
UV_INDEX_URL and UV_EXTRA_INDEX_URL for apps using uv.
SSL_CERT_FILE for certificate configuration.

When an app is built, Databricks uses the workspace configuration unless the app has a permitted override. The certificate settings PIP_CERT and SSL_CERT_FILE always use the workspace-configured values and cannot be overridden in app.yaml.

Python dependencies still belong in the application's dependency file. For a pip-based app, that is usually requirements.txt.

For example:

streamlit==1.38.0
requests==2.31.0
company-data-utils==1.4.2

In this example, company-data-utils is an illustrative internal package. If the configured repository contains that package and the build has access to it, the app can install it without placing the repository URL directly in requirements.txt.

The workspace setting controls the package source. It does not remove the need to declare the libraries your application uses.

Node.js applications

For Node.js apps, Databricks writes the workspace's npm configuration into the app's .npmrc file during deployment.

This allows the build to download JavaScript dependencies from the configured registry, including private packages, without every developer maintaining a separate registry URL and authentication token.

The application's dependencies remain in package.json.

{
  "name": "analytics-dashboard",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "build": "vite build"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "vite": "^5.0.0"
  }
}

This example shows a basic React application using Vite. The actual package versions should match the versions tested by your team.

If your application uses a private JavaScript library, add that library to package.json as well. The configured npm registry must contain the package or provide access to it.

How Administrators Configure the Default Repositories

Workspace administrators can configure the defaults through the Databricks workspace settings.

Follow these steps:

Sign in to the Databricks workspace with an administrator account.
Open the user menu and select Settings.
Open the Compute tab.
Find Default Package Repositories and select Manage.
Add the required Python package index, additional indexes, custom SSL certificate, or npm registry configuration.
Save the changes.

The repository settings can also be managed through Databricks secrets and supported APIs. This is useful for teams that manage workspace configuration through automation.

Managing repository settings with secrets

Databricks supports a predefined secret scope named databricks-package-management for these settings.

For example, an administrator can create the scope and configure access:

databricks secrets create-scope databricks-package-management

databricks secrets put-acl \
  databricks-package-management \
  admins MANAGE

databricks secrets put-acl \
  databricks-package-management \
  users READ

The example grants administrators permission to manage the scope and workspace users permission to read it. Access should be reviewed against your organization's security requirements before applying these permissions.

For a Python repository, the predefined secret key for the primary package index is pip-index-url.

databricks secrets put-secret --json '{
  "scope": "databricks-package-management",
  "key": "pip-index-url",
  "string_value": "https://packages.example.com/simple"
}'

The URL is an example. Replace it with your organization's actual package index.

For npm, the predefined key is npm-rc. Its value contains the content of an .npmrc file, including the registry URL and any required authentication configuration.

databricks secrets put-secret --json '{
  "scope": "databricks-package-management",
  "key": "npm-rc",
  "string_value": "registry=https://npm.example.com/\\n"
}'

This example shows the basic registry setting. If authentication is required, the .npmrc content must include the appropriate authentication configuration. Keep real tokens in secrets rather than committing them to source control.

Can an App Override the Workspace Defaults?

Yes. Workspace-level settings are defaults, not an absolute rule for every app.

Suppose an organization uses an internal Python repository for most applications. One app might need to install a package from a different approved index. The developer can configure an app-specific PIP_INDEX_URL in app.yaml.

A simplified example looks like this:

env:
  - name: PIP_INDEX_URL
    value: https://packages.example.com/simple

Use the actual URL for your repository. If authentication is required, reference a secret using the app's supported secret configuration rather than placing credentials in the file.

For Python package indexes, app-level settings take precedence over the workspace defaults for the supported environment variables. The exception is PIP_CERT and SSL_CERT_FILE, which continue to use the workspace configuration.

For npm, an app can use a different configuration by setting the NPMRC environment variable in app.yaml to reference its own npm configuration.

This flexibility is useful when a workspace contains applications with different dependency requirements. However, developers should not override repository settings without a clear reason. Too many individual overrides can make it harder for administrators to understand which package sources each app uses.

What Happens When Repository Settings Change?

Changing the workspace configuration does not necessarily update an already running app immediately.

For Databricks Apps, changes to repository settings and related secrets take effect the next time the app is built and deployed.

This matters when administrators rotate credentials, change a private registry URL, or update certificate settings. An app that has not been rebuilt may continue running with the dependencies installed during its previous build.

A practical deployment process should therefore include a rebuild after a relevant repository configuration change. Test the build before promoting the updated app to production.

Advantages and Disadvantages

Advantages

Less repeated configuration: Developers no longer need to define the same repository settings in every app.
Central administration: Workspace administrators can manage default package sources and credentials in one place.
Private package support: Apps can install internal Python and JavaScript packages from configured repositories.
App-level flexibility: A project can use its own repository configuration when it has a specific requirement.
Cleaner application files: Dependency files can focus on package names and versions instead of repository credentials.

Disadvantages

A workspace-wide change can affect multiple apps: An incorrect repository URL or expired credential can cause builds to fail across several projects.
Changes require a new build: Updating the repository configuration does not automatically replace the dependencies in an already deployed app.
Version conflicts remain possible: A private repository does not guarantee that every package version is compatible with the application.
Network access is still required: The workspace must be able to reach the configured repository.
Security depends on configuration: Poorly managed credentials or overly broad repository access can expose internal packages or authentication tokens.

Common Problems and Troubleshooting

Problem	What to check
A package cannot be found	Confirm that the package exists in the configured repository and that the app uses the expected index.
Authentication fails during the build	Check the repository credentials stored in Databricks secrets and confirm that they have not expired.
An app still uses the previous repository	Rebuild and redeploy the app after changing workspace repository settings.
One app needs a different Python index	Check its `app.yaml` settings and remove unintended overrides if it should inherit the workspace defaults.
npm packages fail to install	Verify the workspace npm registry configuration and confirm that the package is available through that registry.
Certificate validation fails	Check the configured certificate content and ensure that the repository's certificate chain is trusted.
A dependency change breaks the app	Pin compatible package versions and test the build before deploying the change to production.

Best Practices for Development Teams

Keep dependency declarations in version control. Store Python requirements in requirements.txt or pyproject.toml, and JavaScript dependencies in package.json. Keep the repository configuration separate from the package list.

Pin important package versions. Using explicit versions makes it easier to reproduce builds and investigate compatibility problems. For uv projects, include the appropriate lock file.

Keep credentials out of source control. Store authentication details in Databricks secrets and restrict access to those secrets. Never commit a real access token to app.yaml or .npmrc.

Test repository changes before rollout. A workspace-level setting can affect many applications. Test representative apps after changing the registry, credentials, or certificate configuration.

Use overrides sparingly. Workspace defaults are easier to maintain when most apps inherit them. Add app-specific settings only when the application genuinely needs a different repository.

Review package access. A private repository should contain approved packages and provide only the access required by the workload. Workspace-level defaults simplify configuration, but they do not replace dependency security checks.

Conclusion

Workspace-level Python and npm repositories make dependency management for Databricks Apps easier to maintain. Administrators can configure the default package sources, while developers continue to declare the libraries their applications need.

The feature is especially useful for organizations that maintain many apps or rely on private package repositories. Instead of copying registry settings into each project, teams can inherit common settings and override them when necessary.

The main thing to remember is that centralized configuration does not eliminate dependency management. Developers still need to choose compatible package versions, test builds, and protect credentials. When those practices are in place, workspace-level repositories can reduce repeated configuration and make app deployments more consistent.