Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/prefix-dev/pixi/llms.txt

Use this file to discover all available pages before exploring further.

Synchronizes the global manifest with installed environments. This ensures all environments match their definitions and cleans up any inconsistencies.

​
Usage

pixi global sync
Alias: pixi g sync

​
What It Does

  1. Prunes old environments - Removes environments not listed in the manifest
  2. Syncs each environment - Updates environments to match their manifests
  3. Removes broken files - Cleans up any broken symlinks or files
  4. Prunes completions (Unix only) - Removes outdated shell completion scripts

​
Examples

​
Sync all environments

pixi global sync
Output: 
✓ Synced environment 'python'
✓ Synced environment 'jupyter'
✓ Removed 2 broken files

​
When nothing needs syncing

pixi global sync
Output: 
✓ Nothing to do. The pixi global installation is already up-to-date.

​
When to Use

​
After Manual Changes

If you’ve manually edited the global manifest: 
# Edit ~/.pixi/manifests/pixi-global.toml
vim ~/.pixi/manifests/pixi-global.toml

# Sync the changes
pixi global sync

​
After Errors

If an installation or removal failed: 
pixi global install some-package
# Error occurs...

pixi global sync  # Clean up and restore consistency

​
When Warned

Pixi will warn you when environments are out of sync: 
pixi global list
# Warning: The environments are not in sync with the manifest
# Run: pixi global sync

pixi global sync

​
After System Changes

If you’ve:
  • Restored from backup
  • Moved the pixi directory
  • Manually deleted files
pixi global sync

​
What Gets Synced

​
Packages

  • Installs missing packages
  • Removes packages no longer in the manifest
  • Updates packages to match specified versions

​
Exposed Executables

  • Creates missing symlinks
  • Removes broken symlinks
  • Updates symlink targets

​
Shortcuts

  • Updates desktop/start menu entries
  • Removes outdated shortcuts

​
Completions

  • Updates shell completion scripts (Unix only)
  • Removes completions for removed environments

​
Error Handling

If syncing fails for some environments: 
pixi global sync
Output: 
✓ Synced environment 'python'
✗ Couldn't sync environment 'jupyter'
   Error: Package not found

Error: Some environments couldn't be synced.
Pixi continues syncing other environments even if one fails.

​
Use Cases

​
Restore After Crash

# After a system crash
pixi global sync

​
Clean Installation

# After installing pixi on a new machine and copying manifests
pixi global sync

​
Fix Broken State

# If things seem broken
pixi global sync

​
Verify Installation

# After making changes, verify everything is correct
pixi global sync
pixi global list

​
What Gets Removed

​
Environments

Environments not in the manifest are removed: 
# If you manually deleted an environment from the manifest
pixi global sync  # Removes the environment directory

​
Broken Files

  • Broken symlinks
  • Orphaned executable links
  • Invalid shortcuts

​
Old Completions

Shell completions for removed environments (Unix only).
pixi global sync is safe to run at any time. It only removes files that are no longer referenced in the manifest.

​
Global Manifest Location

The global manifest is stored at:
  • Linux/macOS: ~/.pixi/manifests/pixi-global.toml
  • Windows: %USERPROFILE%\.pixi\manifests\pixi-global.toml

​
Complete Workflow

# Install some packages
pixi global install python jupyter

# Make manual changes
pixi global remove --environment python pip

# Something went wrong, environments out of sync
pixi global list
# Warning: environments not in sync

# Sync everything
pixi global sync

# Verify
pixi global list
# Everything is now in sync
Run pixi global sync regularly to keep your global installation clean and consistent.

​
Differences from Other Commands

CommandPurpose
pixi global syncSynchronize all environments
pixi global installInstall new packages
pixi global removeRemove packages from an environment
pixi global uninstallRemove entire environments

​
Automatic Syncing

Pixi automatically syncs during:
  • pixi global install
  • pixi global remove
  • pixi global uninstall
You typically only need to run pixi global sync manually when:
  • Fixing issues
  • After manual changes
  • When explicitly warned by pixi

Build docs developers (and LLMs) love

Get started for freeTalk to us