Non-Python SDK’s / Server Mode

Moto has a stand-alone server mode. This allows you to use Moto with any of the official AWS SDK’s.


Install the required dependencies using:

pip install moto[server]

You can then start it like this:

$ moto_server

You can also pass the port:

$ moto_server -p3000
 * Running on

If you want to be able to use the server externally you can pass an IP address to bind to as a hostname or allow any of your external interfaces with

$ moto_server -H
 * Running on

Please be aware this might allow other network users to access your server.

Start within Python

It is possible to start this server from within Python, in a separate thread.
By default, this server will start on port 5000, but this is configurable.

from moto.server import ThreadedMotoServer
server = ThreadedMotoServer()
# run tests
client = boto3.client("service", endpoint_url="http://localhost:5000")

Note that the ThreadedMotoServer and the decorators act on the same state, making it possible to combine the two approaches.
See the following example:

class TestThreadedMotoServer(unittest.TestCase):

    def setUp(self):
        self.server = ThreadedMotoServer()

    def tearDown(self):

    def test_load_data_using_decorators(self):
        server_client = boto3.client("s3", endpoint_url="")

        in_mem_client = boto3.client("s3")
        buckets = in_mem_client.list_buckets()["Buckets"]
        self.assertEqual([b["Name"] for b in buckets], ["test"])

This example shows it is possible to create state using the TreadedMotoServer, and access that state using the usual decorators.
Note that the decorators will destroy any resources on start, so make sure to not accidentally destroy any resources created by the ThreadedMotoServer that should be kept.

Run using Docker

You could also use the official Docker image. This is stored in two different repositories:

docker run --rm -p 5000:5000 --name moto motoserver/moto:latest
docker run --rm -p 5000:5000 --name moto
Example docker-compose.yaml

Look at to find more environment variables.

  image: motoserver/moto:latest
    - "3000:3000"
    - MOTO_PORT=3000 # set moto listener port with env var

Example Usage

To use Moto in your tests, pass the endpoint_url-parameter to the SDK of your choice.

For more recent SDK’s, this can be configured using the environment variable AWS_ENDPOINT_URL. See the official AWS documentation:

If your SDK does not support this, here are some code samples to set this parameter the old-fashioned way.

In Python:


In Java:

AmazonSQS sqs = new AmazonSQSClient();

In Scala:

val region = Region.getRegion(Regions.US_WEST_2).getName
val serviceEndpoint = "http://localhost:5000"
val config = new AwsClientBuilder.EndpointConfiguration(serviceEndpoint, region)
val amazonSqs =  AmazonSQSClientBuilder.standard().withEndpointConfiguration(config).build

In Terraform:

provider "aws" {
    region                      = "us-east-1"
    skip_credentials_validation = true
    skip_metadata_api_check     = true
    skip_requesting_account_id  = true
    s3_force_path_style         = true

    endpoints {
        lambda           = "http://localhost:5000"

See the Terraform Docs for more information.

Other languages:

Use ServerMode using the decorators

It is possible to call the MotoServer for tests that were written using decorators. The following environment variables can be set to achieve this:


Whenever a mock-decorator starts, Moto will:

  1. Send a reset-request to http://localhost:5000, removing all state that was kept

  2. Add the endpoint_url parameter to boto3, so that all requests will be made to http://localhost:5000.

Optionally, the http://localhost:5000 endpoint can be overridden by:


This can be used for example in case of docker-compose configuration that runs Moto server in a separate service container.

Calling the reset-API ensures the same behaviour as normal decorators, where the complete state is removed. It is possible to keep the state in between tests, using this environment variable:



Moto comes with a dashboard to view the current state of the system:


Reset API

An internal API endpoint is provided to reset the state of all of the backends. This will remove all S3 buckets, EC2 servers, etc.:"")

Install with Homebrew

Moto is also available to install using Homebrew, which makes it much easier to manage if you’re not using Python as your primary development language.

Once Homebrew is installed, you can install Moto by running:

brew install moto

To make the Moto server start up automatically when you log into your computer, you can run:

brew services start moto


The standalone server has some caveats with some services. The following services require that you update your hosts file for your code to work properly:

  1. s3-control

For the above services, this is required because the hostname is in the form of AWS_ACCOUNT_ID.localhost. As a result, you need to add that entry to your host file for your tests to function properly.