What this error means and why it happens

This error appears when a program on your computer tries to reach Redis — a data storage tool that runs in the background — but cannot find it. Redis listens on a specific address (127.0.0.1) and port (6379) by default. The "connection refused" part means the program knocked on that door and nobody answered.

The most common reasons are: Redis is not running at all, it crashed and stopped, it is running on a different port than your program expects, or a firewall is blocking the connection. This error usually appears in development work, database applications, or caching systems.

Key Takeaways

  • Redis must be running as a background service before any program can connect to it — starting the service is the first step to try.
  • Check whether Redis is actually running on your computer by opening a terminal and typing a simple status command.
  • If Redis is running but the error persists, the port number in your program's settings may not match where Redis is listening.
  • Windows, Mac, and Linux each start Redis differently, so the fix depends on which operating system you use.
  • A firewall or antivirus program can block Redis even when it is running, though this is rare on a single computer.

Check whether Redis is running right now

Open a terminal or command prompt on your computer. On Windows, press the Windows key, type "cmd", and press Enter. On Mac or Linux, open the Terminal application from your Applications folder.

Type this command and press Enter:

redis-cli ping

If Redis is running, you will see the word PONG as the response. If you see an error message or "connection refused", Redis is not running. Write down which response you got — it tells you what to do next.

Start Redis if it is not running

On Windows: Redis does not come built into Windows. You need to download and install it first. Go to the Microsoft Store and search for "Redis", or download the Windows version from the official Redis website. Once installed, open the Start menu, search for "Redis", and click the Redis application to start it. A window will appear showing Redis is running — leave this window open while you work.

On Mac: If you installed Redis using Homebrew (a package manager), type this command in Terminal:

brew services start redis

If you installed Redis another way, type:

redis-server

The second command starts Redis but keeps it running only while Terminal is open. For permanent background running, use the Homebrew command instead.

On Linux: Type this command:

sudo systemctl start redis-server

This starts Redis as a background service. If you get a "command not found" error, Redis is not installed. Install it using your system's package manager (apt on Ubuntu, yum on CentOS, pacman on Arch).

Verify the port number matches your program's settings

Redis listens on port 6379 by default, but your program might be looking for it on a different port. Check your program's configuration file or settings panel for a line mentioning "Redis port", "Redis URL", or "localhost:6379".

If the port number is different — for example, 6380 or 6381 — you have two choices. You can either change your program's settings to use 6379, or you can start Redis on the port your program expects. To start Redis on a different port, use this command (replacing 6380 with your port number):

redis-server --port 6380

After making any change, test the connection again by running redis-cli ping in your terminal.

Check your firewall or antivirus settings

Firewalls and antivirus programs sometimes block applications from listening on certain ports, even on your own computer. This is uncommon for Redis on a single machine, but worth checking if Redis is running and the port is correct.

On Windows, open Windows Defender Firewall (search for "Firewall" in the Start menu). Click "Allow an app through firewall" and look for Redis in the list. If it is there but unchecked, check the box. If it is not there, click "Allow another app" and browse to your Redis installation folder to add it.

On Mac, go to System Preferences > Security & Privacy > Firewall Options and check whether Redis appears in the blocked apps list. On Linux, use your firewall tool (usually ufw or firewalld) to check port 6379 is not blocked.

Restart Redis completely if it is stuck

Sometimes Redis gets into a bad state and needs a full restart. On Windows, close the Redis window completely, wait 10 seconds, and open it again. On Mac or Linux, type this command:

sudo systemctl restart redis-server

Or if you started Redis manually with the redis-server command, press Ctrl+C to stop it, wait 5 seconds, then type redis-server again to start it fresh.

After restarting, run redis-cli ping again to confirm it is responding.

Reinstall Redis if nothing else works

If Redis is running, the port is correct, and your firewall is not blocking it, but the error persists, Redis may be corrupted. Uninstall it completely and reinstall a fresh copy.

On Windows, go to Settings > Apps > Apps & Features, find Redis, and click Uninstall. Then download and install the latest version from the Microsoft Store or the official Redis website. On Mac, if you used Homebrew, type brew uninstall redis and then brew install redis. On Linux, use your package manager to remove and reinstall it (for example, sudo apt remove redis-server and sudo apt install redis-server).

Frequently Asked Questions

Why does my program keep saying connection refused even though I started Redis?

Redis may have crashed or stopped running in the background. Run redis-cli ping again to confirm it is still responding. If you get an error, restart Redis using the commands in the "Start Redis" section above. Also check that your program is looking for Redis on port 6379 — if it is looking on a different port, you need to either change your program's settings or start Redis on that port.

Can I run Redis on a Mac without Homebrew?

Yes. Download the source code from the official Redis website, extract it, and follow the build instructions in the README file. This is more work than using Homebrew, but it works. Most Mac users find Homebrew easier because it handles updates and background running automatically.

What if I see "command not found" when I type redis-cli?

Redis is not installed on your computer, or it is installed in a location your terminal cannot find. On Windows, reinstall Redis from the Microsoft Store. On Mac, install it with Homebrew using brew install redis. On Linux, use your package manager to install redis-tools or redis-client in addition to redis-server.

Does Redis need to run all the time, or only when I am using my program?

Redis only needs to run while your program is using it. If you set it up as a background service (using Homebrew on Mac or systemctl on Linux), it will start automatically when you restart your computer. If you start it manually with the redis-server command, it stops when you close the terminal window or restart your computer.

Can multiple programs use the same Redis instance?

Yes. Once Redis is running on port 6379, any program on your computer can connect to it. This is actually useful — you can run several applications that all share the same data storage. Just make sure they are all configured to use the same port number.