A terminal-based user interface for browsing and managing AWS S3 buckets and objects. Built with Python and Textual, s3ranger provides an intuitive way to interact with S3 storage directly from your terminal.

• Browse S3 buckets and objects with an intuitive file manager interface
• Navigate folder structures seamlessly
• Upload files and directories to S3
• Download files and directories from S3
• Copy and move files and folders within the same bucket or across different S3 buckets
• Delete objects and folders with confirmation prompts
• Rename files and folders with conflict detection
• Filter and search through buckets
• Sort objects by name, type, modification date, or size
• Lazy loading with pagination - buckets and objects load progressively as you scroll
• Multiple themes (GitHub Dark, Dracula, Solarized, Sepia)
• Flexible configuration via CLI arguments or config files
• Multiple authentication methods (AWS profiles, CLI access keys)
• S3-compatible services support (LocalStack, MinIO, etc.)

pip install s3ranger

# Install s3ranger globally
uv tool install s3ranger@latest

# Update to latest version
uv tool upgrade s3ranger

git clone https://github.com/Sharashchandra/s3ranger.git
cd s3ranger
pip install -e .

The recommended way to configure AWS credentials is using the AWS CLI:

aws configure

This sets up your default profile in ~/.aws/credentials and ~/.aws/config.

s3ranger

That's it! s3ranger will use your default AWS profile automatically.

If you work with multiple AWS accounts, you can set up named profiles and switch between them easily.

# Configure your default profile
aws configure

# Configure additional named profiles
aws configure --profile work
aws configure --profile personal

[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[work]
aws_access_key_id = AKIAI44QH8DHBEXAMPLE
aws_secret_access_key = je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY

[personal]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE2
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLE2

[default]
region = us-east-1
output = json

[profile work]
region = us-west-2
output = json

[profile personal]
region = eu-west-1
output = json
# Optional: for S3-compatible services
# endpoint_url = https://s3.custom-endpoint.com

# Use a specific profile via CLI
s3ranger --profile-name work

# Or set a default profile in s3ranger config file (~/.s3ranger.config)
# profile_name = "work"

For quick, one-time access, you can pass credentials directly via CLI:

s3ranger --aws-access-key-id AKIAIOSFODNN7EXAMPLE \
         --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

For temporary credentials (e.g., from AWS STS), include the session token:

s3ranger --aws-access-key-id AKIAIOSFODNN7EXAMPLE \
         --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
         --aws-session-token your-session-token

Note: Direct credentials via CLI are useful for one-off usage but not recommended for regular use. Use AWS profiles for better security and convenience.

s3ranger resolves credentials in the following order (highest to lowest priority):

1. CLI credentials (--aws-access-key-id + --aws-secret-access-key)
2. CLI profile (--profile-name)
3. Config file profile (profile_name in ~/.s3ranger.config)
4. boto3 default resolution - If none of the above are provided, s3ranger lets boto3 resolve credentials using its standard credential chain, which includes environment variables, AWS config files, IAM roles, etc.

CLI arguments always override config file settings.

# Launch the TUI
s3ranger

# Launch with specific AWS profile
s3ranger --profile-name myprofile

# Launch with custom endpoint (for S3-compatible services)
s3ranger --endpoint-url https://s3.amazonaws.com --region-name us-west-2

# Launch with specific theme
s3ranger --theme dracula

# Show help
s3ranger --help

# Interactive configuration
s3ranger configure

s3ranger works with any S3-compatible service. You can configure these services either via CLI arguments or through AWS config files.

LocalStack is a fully functional local AWS cloud stack for testing and development.

Quick start (CLI):

s3ranger --endpoint-url http://localhost:4566 --region-name us-east-1

Using AWS config files:

Add a LocalStack profile to your ~/.aws/credentials:

[localstack]
aws_access_key_id = test
aws_secret_access_key = test

Add the endpoint configuration to your ~/.aws/config:

[profile localstack]
region = us-east-1
output = json
endpoint_url = http://localhost:4566

Then launch s3ranger with the profile:

s3ranger --profile-name localstack

MinIO is a high-performance object storage server compatible with Amazon S3.

Note: For MinIO, the --aws-access-key-id corresponds to your MinIO username and --aws-secret-access-key corresponds to your MinIO password. The default credentials for MinIO are minioadmin / minioadmin.

Quick start (CLI):

s3ranger --endpoint-url http://localhost:9000 --region-name us-east-1 \
         --aws-access-key-id minioadmin \
         --aws-secret-access-key minioadmin

Using AWS config files:

Add a MinIO profile to your ~/.aws/credentials:

[minio]
aws_access_key_id = minioadmin
aws_secret_access_key = minioadmin

Add the endpoint configuration to your ~/.aws/config:

[profile minio]
region = us-east-1
output = json
endpoint_url = http://localhost:9000

Then launch s3ranger with the profile:

s3ranger --profile-name minio

Or set it as default in your s3ranger config (~/.s3ranger.config):

profile_name = "minio"

s3ranger can be configured using a TOML configuration file located at ~/.s3ranger.config:

# AWS Configuration
profile_name = "default"

# UI Configuration
theme = "Github Dark"

# Download Configuration
# Default directory for downloads (defaults to ~/Downloads/)
download_directory = "~/Documents/"

# Performance
# Set to false to load all items at once instead of using pagination
enable_pagination = true

Supported config file options:

• profile_name - AWS profile to use (can be overridden with --profile-name)
• theme - UI theme (Github Dark, Dracula, Solarized, Sepia)
• download_directory - Default directory for downloads (defaults to ~/Downloads/)
• enable_pagination - Enable or disable pagination

Tip: Set download_directory = "." in your config file to always use the current working directory as the default download location. This is useful when you want downloads to go to your project directory.

Note: AWS credentials (aws_access_key_id, aws_secret_access_key, aws_session_token) are only supported via CLI arguments.

Run the configuration wizard to set up your config file:

s3ranger configure

s3ranger uses lazy loading with pagination to handle large numbers of buckets and objects efficiently:

• Bucket list: Loads 250 buckets at a time
• Object list: Loads 25 objects at a time

As you scroll down using the mouse or arrow keys, more items are automatically loaded. This ensures fast initial load times even when you have hundreds of buckets or thousands of objects.

s3ranger comes with several built-in themes:

• GitHub Dark (default) - Dark theme inspired by GitHub's interface
• Dracula - Popular dark theme with purple accents
• Solarized - The classic Solarized color scheme
• Sepia - Warm, vintage-inspired theme

Change themes using:

s3ranger --theme dracula

Or through the configuration file:

theme = "Dracula"

• Python 3.11 or higher
• uv (recommended) or pip

git clone https://github.com/Sharashchandra/s3ranger.git
cd s3ranger

# Using uv
uv sync
uv run s3ranger

# Using pip
pip install -e ".[dev]"
python -m s3ranger.main

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

• Built with Textual by Textualize
• Uses boto3 for AWS S3 integration
• CLI powered by Click
• File picker functionality provided by textual-fspicker

If you encounter any issues or have questions:

• Report bugs
• Request features
• Discussions