Workspace dependencies

Workspace dependencies allow you to manage dependencies centrally at the workspace level. Create shared dependency files that multiple scripts can reference, giving you control over dependency resolution and enabling consistent environments across your workspace.

Quick start

1. Create dependency files in workspace settings under Dependencies
2. Reference them in scripts using annotations like # requirements: myfile

Dependency files location

Locally all dependency files are stored under /dependencies in your workspace:

/dependencies/
├── ml.requirements.in          # Named Python dependencies
├── api.package.json            # Named TypeScript dependencies  
├── web.composer.json           # Named PHP dependencies
├── requirements.in             # Python default (requirements mode)
├── extra.requirements.in       # Python default (extra mode)
└── package.json                # TypeScript default

Naming rules:

• Named files: <name>.<extension> (e.g., ml.requirements.in)
• Unnamed defaults: <extension> or extra.<extension>
• Cannot use default as a filename
• One unnamed default per language (either standard OR extra. form)

Using dependency files in scripts

Requirements mode (explicit dependencies)

Disables import inference, uses only specified files:

# requirements: ml

import pandas as pd
import requests

def main():
    return "Uses only ml.requirements.in"

// package_json: frontend

import axios from 'axios';
import lodash from 'lodash';

export async function main() {
    return "Uses only frontend.package.json";
}

Including workspace defaults

Use default token to include unnamed default files:

# requirements: default
# Includes /dependencies/requirements.in

// package_json: default
// Includes /dependencies/package.json

Supported languages and features

Language	Syntax	Extra implicit	Manual implicit	Manual explicit	Extra explicit
Python	# (extra_)requirements:	❌	✅	one external or less or inline	inline only
TypeScript (Bun)	// (extra_)package_json:	❌	✅	one external or less	❌
PHP	// (extra_)composer_json:	❌	✅	one external or less	❌
Go	// (extra_)go_mod:	❌	❌	❌	❌

Note: Go support not yet available. Extra requirements mode (#extra_requirements:, etc.) is planned for future releases.

Setting up workspace dependencies

Requires workspace admin permissions.

1. Go to workspace settings → Dependencies
2. Create new dependencies files

Creating dependency files

Python example (ml.requirements.in):

pandas>=1.5.0
numpy>=1.21.0
scikit-learn==1.1.2
matplotlib>=3.5.0

TypeScript example (api.package.json):

{
  "dependencies": {
    "axios": "^0.27.2",
    "lodash": "^4.17.21",
    "windmill-client": "^1.147.3"
  }
}

PHP example (web.composer.json):

{
  "require": {
    "guzzlehttp/guzzle": "^7.4",
    "monolog/monolog": "^2.8"
  }
}

Setting workspace defaults

Choose default behavior for scripts without annotations:

Requirements mode default: Creates /dependencies/requirements.in

• Scripts without annotations use this file only
• Import inference disabled by default

important

Creation of workspace defaults will redeploy all existing runnables for given language!

Advanced usage

Opting out of defaults

# requirements:
# Script ignores workspace defaults

import pandas as pd  # Must be available in environment

def main():
    return "No workspace dependencies"

CLI usage

Sync dependency files

# Pull all workspace content including dependencies
wmill sync pull

# Push dependency changes
wmill sync push

Generate lockfiles

# Create lockfile using workspace dependencies
wmill script generate-metadata my_script.py

Manage dependencies

# List available dependency files
ls dependencies

# View dependency file content
cat dependencies/frontend.package.json

Versioning and deployment

• Dependency files are versioned like scripts
• Lockfiles record specific dependency file versions
• Updating dependency files triggers redeployment of dependent scripts

Common patterns

Team-based dependencies

/dependencies/
├── frontend.package.json      # Frontend team deps
├── backend.package.json       # Backend team deps
├── data.requirements.in       # Data team deps
└── shared.requirements.in     # Common dependencies

Environment-based

/dependencies/
├── prod.requirements.in       # Production-ready versions
├── dev.requirements.in        # Development dependencies
└── test.requirements.in       # Testing utilities

Feature-based

/dependencies/
├── ml.requirements.in         # Machine learning
├── api.requirements.in        # API integrations
├── ui.package.json           # UI components
└── data.requirements.in       # Data processing

Troubleshooting

Missing dependencies

• Check annotation syntax: # requirements: filename
• Verify file exists in workspace /dependencies
• Ensure file contains required packages

Annotation conflicts

• Use either # requirements: OR # extra_requirements:, not both
• # requirements: takes precedence if both present

CLI problems

• Upgrade to latest Windmill CLI
• Ensure admin permissions for dependency management
• Check dependency file format validity

Import errors

• Requirements mode disables import inference
• Add missing packages to dependency files
• Consider switching to extra mode if you want inference + workspace deps

For debugging, generate and inspect lockfiles:

wmill script generate-metadata script_path
cat script_path.lock

info

Workspace dependencies replace the previous "raw requirements" system. See migration guide if upgrading from the old system.

Migration guide

Migrate from the previous dependency system to workspace dependencies.

Dependency management overview

Understanding Windmill's dependency resolution and import system.