# Workspace dependencies

> How do I manage shared dependencies centrally at the workspace level in Windmill?

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.

![Workspace dependencies overview](./workspace-dependencies.png)

## 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](../../advanced/6_imports/index.mdx), uses only specified files:

```python
# requirements: ml

import pandas as pd
import requests

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

```typescript
// package_json: frontend

}
```

### Including workspace defaults

Use `default` token to include unnamed default files:

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

```typescript
// 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:` | ❌ | ❌ | ❌ | ❌ |
| PowerShell | `# (extra_)psd1:` | ❌ | ❌ | ❌ | ❌ |

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`):
```txt
pandas>=1.5.0
numpy>=1.21.0
scikit-learn==1.1.2
matplotlib>=3.5.0
```

**TypeScript example** (`api.package.json`):
```json
{
  "dependencies": {
    "axios": "^0.27.2",
    "lodash": "^4.17.21",
    "windmill-client": "^1.147.3"
  }
}
```

**PHP example** (`web.composer.json`):
```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

```python
# 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
```bash
# Pull all workspace content including dependencies
wmill sync pull

# Push dependency changes
wmill sync push
```

### Generate lockfiles
```bash
# Create lockfile using workspace dependencies
wmill generate-metadata my_script.py
```

### Manage dependencies
```bash
# 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:
```bash
wmill script generate-metadata script_path
cat script_path.lock
```

:::info
Workspace dependencies replace the previous "raw requirements" system. See [migration guide](./migration.mdx) if upgrading from the old system.
:::