Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (
Help us improve Python packaging - Donate today!

A utility to enable easy SSH connections to AWS EC2 instances.

Project Description

SSH into your project-specific AWS EC2 instances by name, without having to remember IP addresses & private keys, or a curating a SSH config.

Turn this: ssh -i ~/.ssh/project-key.pem ubuntu@

Into this: aws-ssh compute

Getting Started


AWS-SSH requires Python 2.7 or greater on a POSIX system. You will also need to have the AWS CLI installed and configured.


Pip is the recommended method.

$ pip install aws-ssh

I recommend installing this into a virtualenv, and then symlinking the binaries to your PATH. For example:

$ mkvirtualenv -p $(which python3) aws-ssh # Python 3 recommended
$ pip install aws-ssh
# Assuming ~/bin/ is in your $PATH...
$ ln -s ~/.virtualenvs/aws-ssh/bin/{aws-ssh,awssh,ssh-ec2} ~/bin/
$ deactivate

You should now be able to use AWS-SSH outside of your virtualenv!


Once installed, you need to create a project. Projects are collections of EC2 instances that share a common set of parameters. For example, I may be working on the squanch project, with the following instances in my AWS account:

  • squanch-compute -
  • squanch-web -
  • squanch-data -

Assuming I keep my squanch-related code in ~/code/squanch, I will first need to initialize an AWS-SSH project within that directory:

$ cd ~/code/squanch
$ aws-ssh --init
Please provide the full path ot the directory containing all private keys: ~/.ssh/
Please provide a name for this project: squanch
Please provide the AWS profile to use: default
Please provide the name of the private key used for authentication (including extension): squanch.pem
Please provide the prefix for EC2 names: squanch-
Please provide the root directory for the project: ~/code/squanch

This will create an .awssshconfig file in the project root directory. You can manage it under version control to get the team on the same page :-)

Now that AWS-SSH has been configured, time to connect to an instance!

$ cd ~/code/squanch
$ aws-ssh web
# Successful SSH connection to



  • AWS-SSH attempts to guess the username for an instance by testing various usernames. Right now, the sequence of user names is fixed (and based off common AMI usernames). In a future release, this will be configurable.
  • If your access is dependent on custom routing (e.g., behind a lazy VPN), you may need to abort the connection attempt (via ^C) and manually add a route for the instance.


Contributions welcome! Be sure to use the development package, available under the dev extra.

$ git clone
$ cd aws-ssh
$ pip install -e .[dev]
Release History

Release History

This version
History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
aws-ssh-0.0.1.tar.gz (7.4 kB) Copy SHA256 Checksum SHA256 Source May 17, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting