Skip to main content
The Settings page allows you to customize your DFX Dashboard environment and manage important DFX-related configurations, including automated shell completion setup and comprehensive cache management. This centralized configuration hub ensures optimal development workflow and system performance.

​
Overview

The Settings page is organized into four main configuration tabs designed for comprehensive environment management:

Version Manager

DFX version selection between bundled and system installations

Cache Management

DFX version cache management and installation control

Environment Variables

DFX environment variables configuration and management

Shell Completion

Automated dfx command completion setup for enhanced productivity

​
Configuration Management

  • Version Manager
  • Cache Management
  • Environment Variables
  • Shell Completion

​
Version Manager Tab

Version ManagerThe Version Manager tab provides comprehensive DFX version management capabilities, allowing you to switch between bundled and system DFX installations.

​
DFX Version Selection

Bundled DFX

Utilizes dfx v0.25.0 that comes packaged with the DFX Dashboard app

System DFX

Uses the DFX version installed on your system via dfxvm

​
Bundled DFX Features

Bundled DFX Configuration
  • Guaranteed Compatibility: Ensures compatibility with all dashboard features
  • No Installation Required: Works even if dfx is not installed on your system
  • Quick Setup: Ideal for quick setups or testing environments
  • Version Consistency: Consistent experience across different systems
  • Latest Features: Access to the newest dfx features and improvements
  • Custom Versions: Use specific versions required by your projects
  • System Integration: Better integration with existing development workflows
  • Flexibility: Switch between different dfx versions as needed

​
Installing New Versions

Install New DFX VersionThe Version Manager allows you to install new DFX versions directly from the interface:
1

Select Version

Choose from available DFX versions in the dropdown
2

Install

Click “Install” to download and install the selected version
3

Monitor Progress

Track installation progress with the progress indicator
4

Set as Default

Optionally set the newly installed version as default
The bundled DFX option allows you to use the Dashboard even if dfx is not installed on your system, which can be useful for quick setups or testing. The current system dfx version is displayed next to the toggle (e.g., “dfx 0.25.0”).

​
Profile File Management

When you update environment variables or set up shell completion through the DFX Dashboard, it intelligently manages your shell profile files:

​
Cross-Platform Profile Support

Profile files checked and managed:
  • ~/.bashrc - Primary bash configuration file
  • ~/.bash_profile - macOS fallback for bash
  • ~/.zshrc - Zsh shell configuration
  • ~/.profile - Generic shell profile
  • ~/.config/fish/completions/ - Fish completion directory
Windows Subsystem for Linux support:
  • Uses Linux-style profile files within WSL environment
  • Supports bash, zsh, and fish shells in WSL
  • Handles Windows-specific path considerations
  • Integrates with WSL environment variables
Intelligent file handling:
  • Updates the first existing file found in priority order
  • Creates appropriate files if none exist
  • Prevents duplicate entries in profile files
  • Maintains proper file permissions and ownership
The Dashboard will attempt to update the first existing file it finds in the order listed above, or create the appropriate file if none exist. This ensures compatibility across different system configurations.

​
Best Practices

Optimize your DFX environment configuration:
  • Shell Completion: Enable shell completion for improved command-line productivity
  • Version Management: Regularly check your DFX version to ensure compatibility (0.25.0+ recommended)
  • Documentation: Keep a record of any custom paths or configurations you set
  • Team Consistency: Ensure all team members use consistent environment settings
Optimize your DFX cache management:
  • Regular Cleanup: Remove unused versions to save disk space
  • Version Strategy: Keep only the versions you actively use
  • Backup Important Versions: Keep stable versions for production work
  • Monitor Disk Usage: Check cache size regularly to prevent storage issues
Enhance your development workflow:
  • Version Control: Use version control for your project’s dfx.json file
  • Environment Variables: Regularly review and clean up unused variables
  • Testing: Test shell completion setup in new terminal sessions
  • Updates: Install latest versions for new features and improvements

​
Troubleshooting

Common configuration problems and solutions:Problem: Changes don’t take effect
  • Restart your terminal or the DFX Dashboard
  • Source your profile file manually (e.g., source ~/.bashrc)
  • Check if changes were properly written to profile files
  • Verify environment variable syntax and values
Problem: Shell completion not working
  • Open a new terminal session to load new configuration
  • Manually source the appropriate profile file
  • Verify shell detection with echo $SHELL command
  • Check completion file permissions and accessibility
Version management problems:Problem: Version compatibility problems
  • Ensure dfx version is 0.25.0+ for full feature support
  • Check project requirements against installed versions
  • Verify version installation completed successfully
  • Clear cache and reinstall if version appears corrupted
Problem: Cache management issues
  • Check internet connection for version downloads
  • Verify write permissions to cache directory
  • Ensure sufficient disk space for installations
  • Clear corrupted cache entries and reinstall
Environment variable problems:Problem: Canister operation issues
  • Verify CANISTER_ID and CANISTER_CANDID_PATH are set correctly
  • Check that paths exist and are accessible
  • Ensure proper file permissions for referenced files
  • Validate canister configuration in dfx.json
Problem: Environment variables not recognized
  • Check the appropriate profile file to ensure changes were saved
  • Verify variable syntax and formatting
  • Restart terminal or source profile files manually
  • Check for conflicts with existing environment variables
Platform-specific problems:Problem: Windows WSL issues
  • Ensure you’re running the dashboard within the WSL environment
  • Verify WSL shell detection is working correctly
  • Check WSL file system permissions and access
  • Ensure proper integration between Windows and WSL environments
Problem: Permission errors during setup
  • Ensure write permissions to home directory and profile files
  • Check file ownership and group permissions
  • Verify sudo access if needed for system-wide changes
  • Use appropriate user context for file modifications

​
Advanced Configuration

​
Custom Cache Locations

  • Custom Paths: Configure custom cache directory locations
  • Network Storage: Use network-attached storage for shared caches
  • Symbolic Links: Use symbolic links for flexible cache management
  • Backup Integration: Integrate cache with backup systems
  • SSD Storage: Use SSD storage for faster cache access
  • Memory Caching: Configure memory-based caching for frequently used versions
  • Parallel Downloads: Enable parallel downloads for faster installation
  • Compression: Use compression to reduce cache storage requirements

​
Environment Variable Templates

Development Template

Pre-configured environment variables for development workflows

Production Template

Environment variables optimized for production deployments

Team Template

Shared environment configurations for team collaboration

Custom Template

Create custom environment variable templates

​
Additional Resources

DFX Configuration Reference

Complete reference for DFX configuration options

Environment Variables Guide

Comprehensive guide to DFX environment variables

Shell Completion Documentation

Official documentation for DFX shell completion

Version Management Guide

Guide to managing multiple DFX versions

Cache Management Documentation

Detailed cache management documentation

Troubleshooting Guide

Comprehensive troubleshooting for DFX issues
Ready to learn more about the DFX Dashboard? Continue to the About page for information about the application, version details, and additional resources.
⌘I