Synchronizes the global manifest with installed environments. This ensures all environments match their definitions and cleans up any inconsistencies.
Usage
Alias: pixi g sync
What It Does
- Prunes old environments - Removes environments not listed in the manifest
- Syncs each environment - Updates environments to match their manifests
- Removes broken files - Cleans up any broken symlinks or files
- Prunes completions (Unix only) - Removes outdated shell completion scripts
Examples
Sync all environments
Output:
✓ Synced environment 'python'
✓ Synced environment 'jupyter'
✓ Removed 2 broken files
When nothing needs syncing
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
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:
Output:
✓ Synced environment 'python'
✗ Couldn't sync environment 'jupyter'
Error: Package not found
Error: Some environments couldn't be synced.
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
| Command | Purpose |
|---|
pixi global sync | Synchronize all environments |
pixi global install | Install new packages |
pixi global remove | Remove packages from an environment |
pixi global uninstall | Remove entire environments |
Automatic Syncing
Pixi automatically syncs during:
pixi global installpixi global removepixi global uninstall
You typically only need to run pixi global sync manually when:
- Fixing issues
- After manual changes
- When explicitly warned by pixi