docs: workspace dependencies (#1159)

* docs: workspace dependencies

Signed-off-by: pyranota <[email protected]>

* change feature matrix

Signed-off-by: pyranota <[email protected]>

---------

Signed-off-by: pyranota <[email protected]>

Author: pyranota

changelog/2025-11-28-workspace-dependencies/index.md

@@ -0,0 +1,51 @@
+---
+slug: workspace-dependencies
+version: v1.586.0
+title: Workspace Dependencies
+tags: ['Core concepts', 'Dependencies', 'Script editor']
+description: Centralized dependency management at the workspace level for shared dependency files across scripts.
+image: ./workspace-dependencies.png
+features:
+  [
+    'Centralized dependency management with shared dependency files stored in /dependencies directory.',
+    'Support for Python, TypeScript (Bun), and PHP with language-specific annotations.',
+    'Two dependency modes: requirements mode (explicit) and extra mode (hybrid with inference).',
+    'Dependency file versioning and provenance tracking with Git sync support coming soon.',
+    'CLI integration for managing workspace dependencies alongside scripts and flows.'
+  ]
+docs: /docs/core_concepts/workspace_dependencies
+---
+
+Workspace dependencies provide centralized dependency management at the workspace level. Instead of managing dependencies individually per script, you can now define shared dependency files that multiple scripts can reference.
+
+## Key Features
+
+**Centralized Storage**: All dependency files are stored under `/dependencies` in your workspace, replacing the previous path-based "raw requirements" system.
+
+**Language Support**: Full support for Python (`.requirements.in`), TypeScript/Bun (`.package.json`), and PHP (`.composer.json`) with their respective annotation syntax.
+
+**Flexible Dependency Modes**:
+- **Requirements mode**: Use `# requirements: filename` to disable import inference and use only specified workspace dependencies
+- **Extra mode**: Use `# extra_requirements: filename` to add workspace dependencies while keeping import inference enabled (hybrid approach)
+
+**Versioning**: Dependency files are versioned by Windmill with full provenance tracking. Git sync support is coming soon.
+
+**Admin Control**: Workspace dependency files can only be managed by workspace administrators, ensuring proper governance.
+
+## Migration from Raw Requirements
+
+This feature replaces the previous "raw requirements" system. Users need to manually:
+1. Move existing dependency files to the workspace `/dependencies` directory
+2. Update scripts to use the new annotation syntax
+3. Upgrade to the latest Windmill CLI
+
+See the [migration guide](/docs/core_concepts/workspace_dependencies/migration) for detailed instructions.
+
+## Implementation Status
+
+- ✅ Basic functionality with requirements mode
+- ✅ Python, TypeScript (Bun), and PHP support  
+- ✅ CLI integration
+- ⏳ Git sync support (coming soon)
+- ⏳ Extra requirements mode (planned for next release)
+- ❌ Go support (not yet available)

changelog/2025-11-28-workspace-dependencies/workspace-dependencies.png

@@ -14,6 +14,7 @@ Each workspace can be configured through the following sections:
 - [Object Storage (S3)](../38_object_storage_in_windmill/index.mdx#workspace-object-storage) - Set up S3-compatible storage
 - [Default App](../../apps/1_default_app/index.md) - Configure the default application settings
 - [Encryption](../30_workspace_secret_encryption/index.mdx) - Manage encryption keys and settings
+- [Workspace dependencies](../55_workspace_dependencies/index.mdx) - Centralized dependency management for scripts
 - [General](#general)
 
 ## General

docs/core_concepts/44_workspace_settings/index.mdx

@@ -0,0 +1,311 @@
+import DocCard from '@site/src/components/DocCard';
+
+# 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.
+
+![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`
+3. **Choose your mode**: explicit control or hybrid with import inference
+
+## Dependency files location
+
+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, api
+
+import pandas as pd
+import requests
+
+def main():
+    return "Uses only ml.requirements.in and api.requirements.in"
+```
+
+```typescript
+// package_json: frontend, shared
+
+import axios from 'axios';
+import lodash from 'lodash';
+
+export async function main() {
+    return "Uses only frontend.package.json and shared.package.json";
+}
+```
+
+### Extra mode (hybrid with inference)
+
+Adds workspace dependencies to automatically [inferred imports](../../advanced/6_imports/index.mdx):
+
+```python
+# extra_requirements: ml
+
+import pandas as pd    # Auto-inferred
+import numpy as np     # From ml.requirements.in
+
+def main():
+    return "Combines inference + workspace dependencies";
+```
+
+### Including workspace defaults
+
+Use `default` token to include unnamed default files:
+
+```python
+# requirements: default, ml
+# Includes /dependencies/requirements.in + ml.requirements.in
+```
+
+```typescript
+// package_json: default, api
+// Includes /dependencies/package.json + api.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 dependency files or upload existing ones
+3. Choose standard or `extra.` defaults for each language
+
+<!-- Image placeholder: Workspace dependencies settings interface -->
+
+### 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
+
+**Extra mode default**: Creates `/dependencies/extra.requirements.in`  
+- Scripts without annotations get these dependencies + inference
+- Hybrid mode by default
+
+<!-- Image placeholder: Default dependency file selection -->
+
+## Advanced usage
+
+### Mixing workspace and inline dependencies
+
+```python
+# requirements: ml, api
+# custom-package==1.0.0
+# another-dep>=2.0
+
+import pandas as pd
+
+def main():
+    return "Uses workspace files + inline requirements"
+```
+
+### Multiple dependency files
+
+```python
+# requirements: base, ml, data-processing
+
+def main():
+    return "Combines multiple workspace dependency files"
+```
+
+### Opting out of defaults
+
+```python
+# disable_requirements
+# Script ignores workspace defaults
+
+import pandas as pd  # Must be available in environment
+
+def main():
+    return "No workspace dependencies"
+```
+
+### Empty dependencies
+
+```python
+# empty_requirements  
+# Script has no external dependencies
+
+def main():
+    return "No dependencies at all"
+```
+
+<!-- Image placeholder: Script editor showing dependency annotations -->
+
+## 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 script generate-metadata my_script.py
+```
+
+### Manage dependencies
+```bash
+# List available dependency files
+wmill dependencies list
+
+# View dependency file content
+wmill dependencies show ml.requirements.in
+```
+
+## Versioning and deployment
+
+- Dependency files are versioned like scripts
+- Lockfiles record specific dependency file versions
+- Updating dependency files triggers redeployment of dependent scripts
+- Git sync includes dependency file changes
+
+## 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
+
+### Default file issues
+- Cannot have both standard and `extra.` defaults for same language
+- Choose one: `/dependencies/requirements.in` OR `/dependencies/extra.requirements.in`
+
+### 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.
+:::
+
+<div className="grid grid-cols-2 gap-6 mb-4">
+  <DocCard
+    title="Migration guide"
+    description="Migrate from the previous dependency system to workspace dependencies."
+    href="/docs/core_concepts/workspace_dependencies/migration"
+  />
+  <DocCard
+    title="Dependency management overview" 
+    description="Understanding Windmill's dependency resolution and import system."
+    href="/docs/advanced/imports"
+  />
+</div>