Zed 1.0 Upgrade Guide: What You Need to Know Before Upgrading

Zed, the Rust-built AI-native code editor from Atom's creators, just hit version 1.0—a landmark moment for developers seeking a VSCode alternative optimized for AI pair programming and multi-cursor workflows. But upgrading from Zed's beta versions comes with critical changes that could break your setup. This guide covers everything you need to know before making the jump.

Critical Model ID Changes

The most impactful breaking change in Zed 1.0 is the model identifier system for AI features. If you've configured Claude, GPT-4, or other language models in your settings, model IDs have been standardized and renamed.

What changed: Previous beta versions used inconsistent naming conventions (e.g., claude-2.1, gpt-4-turbo). Zed 1.0 now enforces the official provider model names.

What you must do:

1. Open your settings.json file (Cmd/Ctrl+,)
2. Search for any AI model references
3. Update model IDs to match Zed 1.0's official list:
   • claude-3-5-sonnet (Anthropic)
   • gpt-4o (OpenAI)
   • gpt-4-turbo (legacy—migrate to gpt-4o)
   • gemini-2.0-flash (Google)
4. Verify your API keys are still valid (they should be, but expired credentials won't work)

Settings.json and Config File Restructuring

Zed 1.0 reorganized the settings architecture. If you've hand-edited your settings.json, expect schema changes.

Key structural updates:

The languages section now nests under a language_servers key. Old format:

"languages": {
  "python": {
    "lsp": "pylance"
  }
}

New format:

"language_servers": {
  "pylance": {
    "initialization_options": {}
  }
}

AI collaboration settings have moved from top-level to a dedicated collaboration section. If you configured AI assistant behavior, you'll need to migrate those settings manually—Zed won't auto-migrate custom values.

Action: Back up your current settings.json before upgrading. After installing Zed 1.0, use the GUI settings panel (not raw JSON) to reconfigure critical options. This forces validation and prevents syntax errors.

Breaking Changes You'll Hit

Theme compatibility: Custom themes built for Zed beta versions may not load in 1.0. Check the Zed extensions registry for updated versions. Most popular themes have been updated, but niche themes might require manual fixes.

Extension API changes: If you've built custom extensions, the Zed 1.0 plugin API has breaking changes. The collaboration protocol is now locked for stability, meaning some older extensions won't work. Review your installed extensions in the marketplace and disable anything flagged as "incompatible."

Keybinding names: Multi-cursor commands have been renamed for clarity. editor::add_selection_above is now editor::select_line_above. If you use custom keybindings, audit your keymap.json.

Font rendering: Zed 1.0 uses a new GPU-accelerated renderer. Some monospace fonts render differently—particularly ligatures. Test your preferred font (Fira Code, JetBrains Mono, etc.) immediately after upgrading.

Gotchas That Will Trip You Up

• AI features require re-authentication: Even if your API keys are stored, Zed 1.0 requires you to re-authorize integrations. This is a one-time friction point, but expect a 2-3 minute setup process.
• Copilot integration is no longer built-in: VSCode Copilot users switching to Zed should install the official Copilot extension from the Zed marketplace. The old inline method won't work.
• Settings sync across devices: Zed 1.0 added cloud settings sync, but it's opt-in and disabled by default. If you use Zed on multiple machines, you'll need to manually enable this in preferences or manually copy settings.json again.
• Workspace trust is now enforced: Zed 1.0 won't run untrusted code without explicit permission. Monorepos with custom scripts may trigger repeated trust dialogs.

Cost Impact: AI Features Aren't Free

Zed 1.0 includes built-in AI collaboration and code completion, but you pay for API calls directly to model providers. There's no Zed-hosted tier (unlike VSCode + GitHub Copilot's $10/month subscription).

Budget reality:

• Claude 3.5 Sonnet: ~$0.003 per 1K input tokens
• GPT-4o: ~$0.005 per 1K input tokens
• Heavy multi-file refactoring: $2–$10/day for active developers

If you integrate Anthropic or OpenAI directly, set API spending limits immediately. Zed has no built-in rate limiting.

When NOT to Upgrade Yet

Skip 1.0 if:

• You rely on a niche extension that hasn't been updated (check compatibility first)
• You work in an air-gapped or offline environment (Zed 1.0 requires internet for AI features)
• You use Zed as part of an AI consulting workflow that depends on specific beta behavior—wait for 1.0.1 patch releases to stabilize
• Your team uses VSCode's Live Share for pair programming (Zed's native collaboration is different; migration takes planning)
• You can't absorb per-API-call costs without budget approval

The Bottom Line

Zed 1.0 is production-ready and represents a genuine VSCode alternative, especially for AI-native development workflows. The upgrade is worth it if you're already using Zed's AI features and want stability. But it's not a "just click upgrade"—plan 15–30 minutes for reconfiguration, test your extensions first, and secure your API budgets. For new users evaluating Zed against VSCode, 1.0 is the right entry point.

Now you know more than 99% of people. — Sara Plaintext