windows com port assignment

  Windows OS Hub / Windows 10 / How to Clean Up or Reset COM Port Numbers in Windows

How to Clean Up or Reset COM Port Numbers in Windows

When you connect a new COM device or a USB device to your computer (USB modem, mobile phone, Bluetooth adapter, serial to USB converters, etc.), Windows detects it using Plug-n-Play and assigns it a COM port number in the range of 1 to 255 (COM1, COM2, COM3, etc.). If this device is connected again, the reserved COM ( Communication , or Serial ) port number is assigned to it. A new device gets the first free COM port number. It often happens that when connected, external devices create several COM ports at once. In my case after connecting a Bluetooth adapter 10!!! new COM ports have appeared in the system.

A number of legacy applications are able to address only two-digit COM port numbers, and won’t work with COM100 and higher. In the worst cases, these programs work only with COM1-COM9 ports. What if a device has got a higher COM port number?  Is it possible to reset the numbering for reserved COM ports and delete assigned ports?

How to Change a COM Port Number for a Device in Windows?

Find out which process is using a serial com port in windows, resetting com port numbers in windows registry.

In Windows, you can manually change the COM port number assigned to a device. Suppose the necessary COM port is already busy, and you want to try to free it.

• Open the Device Manager by running the devmgmt.msc command;

• Then expand Ports (COM & LPT) and find your device in the list;
• Go to the Port Settings tab and click the Advanced button;
• The current COM port number assigned to the device can be found in the COM Port Number field;

But more often you cannot change the assigned COM port number to another one in the hardware properties, since all the “lower” COM ports are already in use.In this case, you need to try to remove the COM port reservation

• Expand the Ports (COM & LPT) branch, find which COM port number you need is assigned to (a pale icon means that this COM port is assigned, but this device is not currently connected);

However, this method does not allow you to free the busy COM port in all cases.

Get-WMIObject Win32_SerialPort | Select-Object Name,DeviceID,Description You can get the COM port number for a specific device by its name, for example:

Get-WMIObject Win32_SerialPort | Where-Object { $_.Name -like "*Arduino*"}|select name, deviceid or Get-WMIObject Win32_SerialPort | Where-Object { $_.Name -like "*GPS*"}|select name, deviceid

You won’t be able to release the COM port of a device that is used by Windows or a running program (process). First, you need to stop the process that is currently using the COM port. You can use the Process Explorer tool (by Sysinternals) to find out the name of the process using a particular COM port number ( https://docs.microsoft.com/en-gb/sysinternals/downloads/process-explorer ).

First, you need to display the name of the service that uses the COM port. Run the PowerShell command:

get-pnpdevice -class Ports -ea 0| Select Name, PNPDeviceID, Status, Service

The service name of the specific COM port is shown in the Service column. For example, for COM2 it is Serial . Now you need to run Process Explorer as an administrator and select Find -> Find Handle or DLL from the menu. In the Handle or DLL substring line, enter the Service value obtained earlier. In our example, this is Serial .

Process Explorer should show the process name that is currently using your COM port. To release the COM port, kill the process or program.

Information about the COM ports in use is stored in CommDB registry parameter under the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\COM Name Arbiter reg key.

• Unplug all external devices and restart your computer;
• After the reboot, connect the devices in the necessary order, reinstall USB-to-serial converters, etc. All detected COM port devices will be automatically detected by the system and assigned sequential COM port numbers.

You can also use the following free tools to clean up reserved COM ports:

• Device Cleanup Tool – the utility is used to search the registry for previously connected devices (under the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Enum ), remove unused devices, and clear COM port reservations.

Mailbox Size and Quotas in Exchange 2019/2016 and Microsoft 365

Can’t access shared folders or map network drives from windows 10 and 11, related reading, how to hide or show the ‘safely remove..., enable hyper-v on windows 10/11 pro and home..., how to hide or show specific settings pages..., mount physical and network drives in wsl2 (windows..., change network connection (adapter) priorities in windows.

Hi dear When I open Device Manager there is no branch of (COM & LPT) to expand. How can I Add or Find it?

thank you so much

thanks you so much , life saving post 🙂 , i mostly work with iot devices and sometime com ports get busy and am getting com port busy returns in code so this saved my life in flushing com port

Thank you for the post, very helpful

Leave a Comment Cancel Reply

Notify me of followup comments via e-mail. You can also subscribe without commenting.

Current ye@r *

Leave this field empty

Stack Exchange Network

Stack Exchange network consists of 183 Q&A communities including Stack Overflow , the largest, most trusted online community for developers to learn, share their knowledge, and build their careers.

Q&A for work

Connect and share knowledge within a single location that is structured and easy to search.

Change COM Port Number programmatically

In Device Manager, I can right click on a serial device, navigate to the Port Settings tab, click Advanced, and change the COM Port Number via a drop-down menu.

I need to automate this step across a large number of PCs. Is there a way to script this process, or to do it programmatically?

• serial-port

• Are they all the same version of Windows? –  End Antisemitic Hate Commented Dec 11, 2014 at 6:46
• They are not - could be WinXP, Win7, or Win8. Having said that, I'll happily accept a solution that only works on one (better than nothing!) –  Matthew King Commented Dec 11, 2014 at 6:51
• Hmmm....curious what is the specific application for this process? –  mdpc Commented Dec 11, 2014 at 7:22

This question is probably best asked on stack overflow . That said, take a look at ComDBReleasePort and ComDBClaimPort in the COM Port Database . However, changing COM port assignments programmaticly is not exactly considered a best practice. For example, what happens if two more more concurrent applications are fighting to get the same COM assignment?

Windows dynamically assigns COM port numbers for a good reason. Ideally, your application should be written so that it searches for the specific COM port it needs. This can be done via polling or by using the Windows Management Interface (WMI) .

If you're referencing some application that someone else wrote, and you're just stuck with someone else's program design (or lack thereof), then you may want to consider adding a batch script to modify the registry key under HKLM\Hardware\DEVICEMAP\SERIALCOMM at startup, since the new value(s) are not likely to hold between re-boots.

I don't know how how well this last option would work, but if you're a serious PowerShell or Python user, you could theoretically use either scripting language to directly access the APIs mentioned at the beginning of my response for a one-time COM port re-assignment.

You must log in to answer this question.

Not the answer you're looking for browse other questions tagged windows serial-port com-port ..

• The Overflow Blog
• Where does Postgres fit in a world of GenAI and vector databases?
• Mobile Observability: monitoring performance through cracked screens, old...
• Featured on Meta
• Announcing a change to the data-dump process
• Bringing clarity to status tag usage on meta sites

Hot Network Questions

• I would like to add 9 months onto a field table that is a date and have it populate with forecast date 9 months later
• Can stockfish provide analysis with non-standard pieces like knooks?
• What is this device in my ceiling making out of battery chirps?
• How to disable Google Lens in search when using Google Chrome?
• What is the purpose of these 33-ohm series resistors on the RMII side of the LAN8742A?
• How does the summoned monster know who is my enemy?
• Can I endow the following 3-manifold with a hyperbolic metric?
• Why was this lighting fixture smoking? What do I do about it?
• Is 3 ohm resistance value of a PCB fuse reasonable?
• What is opinion?
• Is there a phrase for someone who's really bad at cooking?
• What happens when touching a piece which cannot make a legal move?
• I overstayed 90 days in Switzerland. I have EU residency and never got any stamps in passport. Can I exit/enter at airport without trouble?
• Is the ILIKE Operator in QGIS not working correctly?
• Determining Error Rate of Phase Shift Keying via Monte Carlo Simulation
• Do angels have different dwelling places?
• If the Hom-space of finite length modules is generated by single elements, must the elements be conjugate?
• Whence “uniform distribution”?
• Why are complex coordinates outlawed in physics?
• ESTA is not letting me pay
• Stuck on Sokoban
• What does "CD military" mean on this sign at this crossing point between East Berlin and West Berlin? (June/July 1989)
• Is it possible to have a planet that's gaslike in some areas and rocky in others?
• Many LaTeX packages missing after upgrading from 22.04 to 24.04.1

How to Fix COM Ports Missing in Device Manager Windows 10, 11

This article brings to light the three most effective solutions for the COM ports missing in the Device Manager problem.

COM ports facilitate the connection between a serial device and your computer. You can find the COM ports in the Device Manager as its crucial component. However, many users have reportedly found the COM ports missing in Device Manager.

Are you also among those users? If yes, you need not fret, as this article has the best possible solutions to the issue you are experiencing.

However, before fixing the Windows 11/Windows 10/Windows 7 COM ports missing in the Device Manager issue, let us understand the factors responsible for it. If you know why the problem may have occurred, solving it becomes as simple as ABC.

Hence, the following section shares the possible reasons COM ports are not showing in the Device Manager.

Why Are COM Ports Missing in Device Manager

The following factors may be responsible for the Windows 7/Windows 10/Windows 11 COM ports missing in the Device Manager issue.

• Outdated motherboard drivers
• Recent software changes
• Outdated COM port drivers

The above were some common reasons you may find COM ports missing in Device Manager. Let us look at the tried and tested fixes for this issue.

Fixes for COM Ports Missing in Device Manager (100% Working)

Below are the solutions you can try to get rid of the COM ports missing in Device Manager issues.

Fix 1: Enable the Option to Show Hidden Devices

Windows updates and other software changes can disable the option to view the port on your device, leading to the COM ports missing in the Device Manager issue. Thus, you can follow these steps to enable it.

• Firstly, right-click the Windows icon on your taskbar.

• Select View from the top menu.

• Lastly, check whether or not the issue is resolved. If it remains unresolved, try the below fixes.

Also Read: How to Enable or Disable USB Ports in Windows 10/8/7

Fix 2: Update Drivers (Recommended)

Outdated motherboard or COM port drivers are among the top reasons you find COM ports missing in Device Manager. The driver is a connecting bridge between your computer and peripheral devices, enabling them to communicate with each other. Out-of-date drivers result in many annoying PC problems and updating them solves a lot of these issues.

Hence, you can update the drivers on your computer to solve the problem. You can update drivers automatically in no time with a single click using expert software like Bit Driver Updater .

The Bit Driver Updater updates all outdated drivers on your computer automatically with one click of the mouse. Moreover, it offers many other advantages like scheduled scans for out-of-date drivers, driver backup and restoration, driver download speed acceleration, ignore option for the drivers you do not wish to scan, and a lot more.

You can download and install this wonderful software from the following link to try it.

Bit Driver Updater scans your computer for two to three seconds after its installation. Once the scan is done, a list appears on your screen showing all the outdated drivers present on your computer.

Bit Driver Updater also boasts options to update the motherboard or COM port drivers individually. However, updating all drivers is a better choice to ensure your PC performs smoothly without any errors.

Also Read: Asus USB BT500 Drivers Download and Update for Windows 10, 11

Fix 3: Try Manual COM Port Addition

If none of the above solutions happens to solve the problem, you can add the COM ports manually to fix the COM ports missing in the Device Manager issue. Here is the step-by-step way to do it.

• Now, choose Action from the menu at the top.

• Now, choose Next to proceed to the next step.

• Now, select Standard port types or the manufacturer for ports and select Next. 
• Lastly, select Finish to conclude the above process.

Also Read: Fresco Logic USB Display Driver Download & Update for Windows

COM Ports Missing in Device Manager (Fixed)

This article brought to fore the top fixes for the Windows 11/Windows 10/Windows 7 COM port missing in the Device Manager issue. However, you need not try all these solutions. You can start with the first fix and keep moving to the next solution until the problem is resolved.

However, if you do not have much time, you can directly perform driver updates using Bit Driver Updater to solve the problem. In case of any confusion or questions about this article, please contact us in the comments section.

Leave a Response Cancel reply

Sign me up for the newsletter!

Subscribe to Our Newsletter and stay informed

Don't worry we don't spam

Related Posts

How to Download Steam Deck Windows Drivers

How to Convert YouTube Video in Shorts on Android & iPhone/iPad

27 Best Free Drawing Software/Programs For Windows In 2024

How to View Computer Port Assignments

• Small Business
• Business Technology & Customer Support
• ')" data-event="social share" data-info="Pinterest" aria-label="Share on Pinterest">
• ')" data-event="social share" data-info="Reddit" aria-label="Share on Reddit">
• ')" data-event="social share" data-info="Flipboard" aria-label="Share on Flipboard">

How to Deactivate the Proxy Server

How to log in to a router with hyperterminal, how to connect an android-based phone with froyo to a usb.

• How to Transfer Printer Queue to Another Printer
• How to Turn Off SPI on a NETGEAR Router

With 65,535 possible ports to keep track of, you might think viewing the active ports on your small business' computer is a difficult task. In most cases, the number of assigned ports on the computer will be much smaller than the maximum number. In fact, most computers will use only a few port assignments during normal operation. There is a simple method to view your currently assigned ports in a DOS session with a single command.

Press the “Windows-R” keys.

Type “cmd” without the quotation marks in the “Run” dialog box and click the “OK” button.

Type “netstat -n” at the command prompt and press the “Enter” key. A list of active connections and their port assignments will be displayed on the screen. The assigned port numbers appear immediately after the colon at the end of your IP address.

• The TCP/IP Guide: TCP Common Applications and Server Port Assignments
• Internet Assigned Numbers Authority: Service Name and Transport Protocol Port Number Registry
• A complete list of options for the netstat command is available by typing “netstat/?” at the command prompt.

Finn McCuhil is a freelance writer based in Northern Michigan. He worked as a reporter and columnist in South Florida before becoming fascinated with computers. After studying programming at University of South Florida, he spent more than 20 years heading up IT departments at three tier-one automotive suppliers. He now builds wooden boats in the north woods.

Related Articles

How to enable a computer printer port, how to connect to a mediacom router, how to make your linkedin contact visible, how to hook up a microphone and headset to a computer, how to find the ip address of a local printer in vista, how to flush dns in ie, how to repair a serial port in windows 7, how to remove a dot4 printer port, how to temporarily disable your logitech webcam, most popular.

• 1 How to Enable a Computer Printer Port
• 2 How to Connect to a Mediacom Router
• 3 How to Make Your LinkedIn Contact Visible
• 4 How to Hook Up a Microphone and Headset to a Computer

This browser is no longer supported.

Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.

USB Serial Adapter COM Port Assignment Changes on Windows 10 Reboot

I have a Windows 10 Pro laptop with a USB Serial Adapter with an attached printer. Every time I reboot, the COM Port assigned to the adapter changes. Sometimes it is COM3, other times COM4. When the COM port changes, the printer port assignment is wrong and the printer no longer works.

What can I do so the same COM port is always assigned to the USB Serial Adapter every time the computer reboots?

Windows 10 Setup Windows 10: A Microsoft operating system that runs on personal computers and tablets. Setup: The procedures involved in preparing a software program or application to operate within a computer or mobile device. 1,939 questions Sign in to follow Follow

@Michael Schumann Hi,

Just checking in to see if the information provided was helpful.

If the reply helped you, please remember to accept as answer. If no, please reply and tell us the current situation in order to provide further help.

We have not get information from you for several days.

If the reply is useful for you, please accept as answer. It will be helpful to other members who have same questions. If you have any other confuse, please reply to us directly.

What if you have a docking station where the USB Serial adapter is plugged into and you would want to use different laptops? Example: The front office where employees use a laptop and just want to plug in and operate the pin machine so customers can pay with a card?

@Michael Schumann Hi, The Windows assign the COM port according VID, PID and serial number. So with the same device plug in, it should always get same COM port assignment. However, two devices with same VID, PID and serial number might be treated as same device. Try setting the COM number manually in Device Manager:

• Open Windows Device Manager > right click the device > Properties
• Under Port tab > Advanced
• Change COM port number

If the cable is connected to the same USB port, it should get the same COM number. Hope above information can help you.

============================================

If the Answer is helpful, please click "Accept Answer" and upvote it. Note: Please follow the steps in our documentation to enable e-mail notifications if you want to receive the related email notification for this thread.

This did not solve the problem. I ended up moving the USB - Serial Adapter to another USB port on the computer. I have not run into the problem since, but it's only been a couple of days, so I am keeping my fingers crossed.

I had a motor axis crash between two axes because the motor controllers with identical VID,PID were assigned different by windows. What can <i do to fix assignment of com ports?

• Search forums
• Windows 10 Forums
• General Discussion

Force assign COM ports using command line.

• Thread starter Fugazi
• Start date Apr 20, 2017
• Apr 20, 2017

Hi, please move if this is in the wrong place. I need to force Windows 10 to accept two USB devices on specific COM Ports and have come up blank on how to do this via Command Line. I can clear all 'hidden' devices to ensure the required COM Ports are free using the following code - Code: @ECHO OFF FOR %%i IN (C D E F G H I J K) DO IF EXIST %%i:\remove.cmd SET Drive=%%i: %DRIVE%\DEVCON Find * | FIND /I /V "matching device(s)" > "%DRIVE%\DevicesExist.txt" FOR /F "tokens=1 delims=: " %%A IN ('%DRIVE%\DEVCON FindAll * ^| FIND /I /V "%DRIVE%\matching device(s)"') DO ( TYPE "%DRIVE%\DevicesExist.txt" | FIND "%%~A" >NUL IF ERRORLEVEL 1 %Debug% %DRIVE%\DEVCON Remove "@%%~A" ) Del "%DRIVE%\DevicesExist.txt" But when I plug in the two Devices I need to assign them to COM Port 4 & 5 respectfully .. does anyone have any idea how to go about this .. I understand it will require adjusting registry entries. TIA for any help  

• Open Device Manager
• Expand Ports (COM & LPT)
• Right-click on the device you want to change com port on, and select Properties
• Select the Port Settings tab
• Click the Advanced button
• Select the Com you want and click OK
• Apr 24, 2017

Yes I could .. but I need to do it using Command line programming.  

Well you could take a look at the DEVCON information page produced by Microsoft: https://msdn.microsoft.com/en-us/windows/hardware/drivers/devtest/devcon-restart There may be some useful information there. In earlier editions of Windows there was the change portX = portY command, but the problem with that is it only assigns the port while User is logged on, thus you'd have to do this each time you wished to used your device. To be honest I'm not even sure whether that very old MS-Dos is even supported now. So it seems you will need to download support packages as you apparently already have done re the DEVCON  

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Similar Threads

How-To Geek

Sd card not showing up in windows 10 ways to fix it.

Your changes have been saved

Email is sent

Email has already been sent

Please verify your email address.

You’ve reached your account maximum for followed topics.

Corbin Davenport / How-To Geek

Quick Links

Make sure your sd card isn't locked, ensure the connection isn't loose, clean the card, the card reader, and the card slot, ensure that the card or the reader isn't faulty, enable the sd card, update the sd card driver, assign a drive letter to your sd card, run the chkdsk scan, ensure the sd card isn't write-protected, format your sd card.

Is your SD card not showing up in the File Explorer? Issues like SD card corruption, a faulty card reader, a missing drive letter, outdated drivers, and more could cause the SD card detection issue on your PC. Follow the below tips to identify the primary cause and resolve the problem.

Many full-sized SD cards feature a physical locking switch that can lock the card when moved to the bottom position. Typically, this lock switch is mounted on the front side of the card, usually on the left. If you encounter an error message like "Memory Card Locked" when connecting the card to your device, then the card is likely locked.

So, remove the card from your device and check if the switch is locked. If so, flip the switch upwards to unlock it, which should resolve the issue.

Ensure that the SD card is inserted correctly in its slot, mainly if it's the first time you're inserting it. An SD card should not go beyond a certain point if properly plugged in. Gently press the card inwards to check if it moves slightly inward; if it does, the card isn't correctly plugged in. Check if your laptop detects the card now.

If you're using an external card reader, ensure that the card is correctly inserted into the reader and that the reader itself is securely connected to the USB port. If the card appears fully inserted, try removing and reinserting the card or reader to see if it resolves the issue. If not, go to the next troubleshooting step.

Dust accumulation on your SD card, the card reader, or inside the card slot can interfere with the card's detection. To rule out this possibility, take a soft cotton cloth and gently wipe the dust off the surface of the SD card. If you're inserting the card directly into a slot on your laptop, clean the dust from within the slot.

Avoid blowing air inside, as it can push the dust further in, potentially causing more resistance to card detection. If you're using an external SD card reader, clean the dust from its card slot and the USB head. Also, clean the port where you intend to insert the SD card reader. If cleaning fails to resolve the issue, go to the next troubleshooting step.

To ensure your SD card is not corrupted, try inserting it into another laptop. If you're using a micro SD card via a card reader, test it on your smartphone to check for any faults. If the other laptop or smartphone successfully detects the card, it confirms that the card has no hardware issue and the problem lies elsewhere.

If you're using a card reader, connect it to a different device to confirm that it is not faulty. Also, try plugging the card reader into a different port to rule out any issues with the USB port.

Ensure the SD card is enabled in Device Manager. To do this, right-click the Start button and open "Device Manager." Expand the "Portable Devices" category and look for the SD card. If you don't see it, click the "Action" tab and select "Scan for Hardware Changes" to scan for hardware changes on your computer.

If the SD card appears detected, check if it's enabled. Right-click on the SD card device and select "Properties." Then, go to the "Driver" tab. If you see an "Enable Device" option here, click it to enable the card. If you see a "Disable Device" option, the card is already enabled. In that case, you don't have to do anything.

If the card is enabled but does not appear in File Explorer, ensure its drivers are fully up-to-date. Download the latest drivers from the manufacturer's website. If the driver file is in executable format, run the file and follow the on-screen instructions. If manual installation is required, right-click the device in Device Manager and select "Update Driver."

Then, select "Browse My Computer for Drivers," select the downloaded drivers, and allow Device Manager to update the SD card drivers automatically.

If an SD card has no hardware issue, your device should detect it. To confirm this, press Win+R, type diskmgmt.msc in the Run command, and click "OK."

If the SD card appears detected here but isn't showing in File Explorer, ensure a drive letter is assigned to it. If no drive letter is assigned, your system won't detect it. If no drive letter is assigned, right-click on your SD card and select "Change Drive Letter and Paths."

Then, click the "Add" button, select a new drive letter from the drop-down list, and click "OK."

If the drive letter is already assigned, check the drive for file system errors.

Drive corruption can also prevent the detection of an SD card. To ensure that's not the issue, you should repair the corrupted drive sectors. The CHKDSK scan can help with this. This scan checks for file system errors and repairs them if found. To run the scan, right-click on the SD card volume and select "Properties."

Navigate to the "Tools" tab and click the "Check" button. Then, click on "Scan and Repair Drive" from the popup.

If your SD card shows up in File Explorer, but you can't transfer or modify any data, the card's access permissions (or file attributes) could be set to read-only. To remove the write protection, type Command Prompt in Windows Search and click "Run as Administrator."

Type diskpart and press Enter. Then, type list disk to display your storage devices. Find your SD card by size, and type select disk # , where "#" represents the number of your SD card from the listed storage devices. Finally, type attributes disk clear readonly and press Enter. Doing so will remove the write protection , allowing your SD card to be used again.

If none of the previous solutions resolve the issue, consider formatting the SD card. Formatting often fixes underlying corruption that may prevent the card from being detected. However, remember that formatting will erase all data on the card. If the data on the card is essential, it's best to skip this step. If the card doesn't contain crucial data, you can format it.

To format the SD card, press Win+R, type diskmgmt.msc in the Run command, and click "OK." Then, right-click on the SD card volume and select "Format."

Choose your preferred File System and click "OK." Finally, click "OK" in the confirmation popup to start the formatting process. Recheck the SD card to see if it's accessible now.

Hopefully, the above fixes will help you identify the primary cause and make the SD card detectable again. If the card is permanently corrupted, consider replacing it with a new one .

Services top-level elements

A service is an abstract definition of a computing resource within an application which can be scaled or replaced independently from other components. Services are backed by a set of containers, run by the platform according to replication requirements and placement constraints. As services are backed by containers, they are defined by a Docker image and set of runtime arguments. All containers within a service are identically created with these arguments.

A Compose file must declare a services top-level element as a map whose keys are string representations of service names, and whose values are service definitions. A service definition contains the configuration that is applied to each service container.

Each service may also include a build section, which defines how to create the Docker image for the service. Compose supports building docker images using this service definition. If not used, the build section is ignored and the Compose file is still considered valid. Build support is an optional aspect of the Compose Specification, and is described in detail in the Compose Build Specification documentation.

Each service defines runtime constraints and requirements to run its containers. The deploy section groups these constraints and allows the platform to adjust the deployment strategy to best match containers' needs with available resources. Deploy support is an optional aspect of the Compose Specification, and is described in detail in the Compose Deploy Specification documentation. If not implemented the deploy section is ignored and the Compose file is still considered valid.

Simple example

The following example demonstrates how to define two simple services, set their images, map ports, and configure basic environment variables using Docker Compose.

Advanced example

In the following example, the proxy service uses the Nginx image, mounts a local Nginx configuration file into the container, exposes port 80 and depends on the backend service.

The backend service builds an image from the Dockerfile located in the backend directory that is set to build at stage builder .

For more example Compose files, explore the Awesome Compose samples .

annotations

annotations defines annotations for the container. annotations can use either an array or a map.

When attach is defined and set to false Compose does not collect service logs, until you explicitly request it to.

The default service configuration is attach: true .

build specifies the build configuration for creating a container image from source, as defined in the Compose Build Specification .

blkio_config

blkio_config defines a set of configuration options to set block IO limits for a service.

device_read_bps, device_write_bps

Set a limit in bytes per second for read / write operations on a given device. Each item in the list must have two keys:

• path : Defines the symbolic path to the affected device.
• rate : Either as an integer value representing the number of bytes or as a string expressing a byte value.

device_read_iops, device_write_iops

Set a limit in operations per second for read / write operations on a given device. Each item in the list must have two keys:

• rate : As an integer value representing the permitted number of operations per second.

Modify the proportion of bandwidth allocated to a service relative to other services. Takes an integer value between 10 and 1000, with 500 being the default.

weight_device

Fine-tune bandwidth allocation by device. Each item in the list must have two keys:

• weight : An integer value between 10 and 1000.

cpu_count defines the number of usable CPUs for service container.

cpu_percent

cpu_percent defines the usable percentage of the available CPUs.

cpu_shares defines, as integer value, a service container's relative CPU weight versus other containers.

cpu_period configures CPU CFS (Completely Fair Scheduler) period when a platform is based on Linux kernel.

cpu_quota configures CPU CFS (Completely Fair Scheduler) quota when a platform is based on Linux kernel.

cpu_rt_runtime

cpu_rt_runtime configures CPU allocation parameters for platforms with support for realtime scheduler. It can be either an integer value using microseconds as unit or a duration .

cpu_rt_period

cpu_rt_period configures CPU allocation parameters for platforms with support for realtime scheduler. It can be either an integer value using microseconds as unit or a duration .

cpus define the number of (potentially virtual) CPUs to allocate to service containers. This is a fractional number. 0.000 means no limit.

When set, cpus must be consistent with the cpus attribute in the Deploy Specification .

cpuset defines the explicit CPUs in which to allow execution. Can be a range 0-3 or a list 0,1

cap_add specifies additional container capabilities as strings.

cap_drop specifies container capabilities to drop as strings.

cgroup specifies the cgroup namespace to join. When unset, it is the container runtime's decision to select which cgroup namespace to use, if supported.

• host : Runs the container in the Container runtime cgroup namespace.
• private : Runs the container in its own private cgroup namespace.

cgroup_parent

cgroup_parent specifies an optional parent cgroup for the container.

command overrides the default command declared by the container image, for example by Dockerfile's CMD .

The value can also be a list, in a manner similar to Dockerfile :

If the value is null , the default command from the image is used.

If the value is [] (empty list) or '' (empty string), the default command declared by the image is ignored, i.e. overridden to be empty.

Configs allow services to adapt their behaviour without the need to rebuild a Docker image. Services can only access configs when explicitly granted by the configs attribute. Two different syntax variants are supported.

Compose reports an error if config doesn't exist on the platform or isn't defined in the configs top-level element in the Compose file.

There are two syntaxes defined for configs: a short syntax and a long syntax.

You can grant a service access to multiple configs, and you can mix long and short syntax.

Short syntax

The short syntax variant only specifies the config name. This grants the container access to the config and mounts it as files into a service’s container’s filesystem. The location of the mount point within the container defaults to /<config_name> in Linux containers, and C:\<config-name> in Windows containers.

The following example uses the short syntax to grant the redis service access to the my_config and my_other_config configs. The value of my_config is set to the contents of the file ./my_config.txt , and my_other_config is defined as an external resource, which means that it has already been defined in the platform. If the external config does not exist, the deployment fails.

Long syntax

The long syntax provides more granularity in how the config is created within the service's task containers.

• source : The name of the config as it exists in the platform.
• target : The path and name of the file to be mounted in the service's task containers. Defaults to /<source> if not specified.
• uid and gid : The numeric UID or GID that owns the mounted config file within the service's task containers. Default value when not specified is USER running container.
• mode : The permissions for the file that is mounted within the service's task containers, in octal notation. Default value is world-readable ( 0444 ). Writable bit must be ignored. The executable bit can be set.

The following example sets the name of my_config to redis_config within the container, sets the mode to 0440 (group-readable) and sets the user and group to 103 . The redis service does not have access to the my_other_config config.

container_name

container_name is a string that specifies a custom container name, rather than a name generated by default.

Compose does not scale a service beyond one container if the Compose file specifies a container_name . Attempting to do so results in an error.

container_name follows the regex format of [a-zA-Z0-9][a-zA-Z0-9_.-]+

credential_spec

credential_spec configures the credential spec for a managed service account.

If you have services that use Windows containers, you can use file: and registry: protocols for credential_spec . Compose also supports additional protocols for custom use-cases.

The credential_spec must be in the format file://<filename> or registry://<value-name> .

When using registry: , the credential spec is read from the Windows registry on the daemon's host. A registry value with the given name must be located in:

The following example loads the credential spec from a value named my-credential-spec in the registry:

Example gMSA configuration

When configuring a gMSA credential spec for a service, you only need to specify a credential spec with config , as shown in the following example:

With the depends_on attribute, you can control the order of service startup and shutdown. It is useful if services are closely coupled, and the startup sequence impacts the application's functionality.

The short syntax variant only specifies service names of the dependencies. Service dependencies cause the following behaviors:

Compose creates services in dependency order. In the following example, db and redis are created before web .

Compose removes services in dependency order. In the following example, web is removed before db and redis .

Simple example:

Compose guarantees dependency services have been started before starting a dependent service. Compose waits for dependency services to be "ready" before starting a dependent service.

The long form syntax enables the configuration of additional fields that can't be expressed in the short form.

restart : When set to true Compose restarts this service after it updates the dependency service. This applies to an explicit restart controlled by a Compose operation, and excludes automated restart by the container runtime after the container dies. Introduced in Docker Compose version 2.17.0 .

condition : Sets the condition under which dependency is considered satisfied

• service_started : An equivalent of the short syntax described above
• service_healthy : Specifies that a dependency is expected to be "healthy" (as indicated by healthcheck ) before starting a dependent service.
• service_completed_successfully : Specifies that a dependency is expected to run to successful completion before starting a dependent service.

required : When set to false Compose only warns you when the dependency service isn't started or available. If it's not defined the default value of required is true . Introduced in Docker Compose version 2.20.0 .

Service dependencies cause the following behaviors:

Compose waits for healthchecks to pass on dependencies marked with service_healthy . In the following example, db is expected to be "healthy" before web is created.

Compose guarantees dependency services are started before starting a dependent service. Compose guarantees dependency services marked with service_healthy are "healthy" before starting a dependent service.

deploy specifies the configuration for the deployment and lifecycle of services, as defined in the Compose Deploy Specification .

develop specifies the development configuration for maintaining a container in sync with source, as defined in the Development Section .

device_cgroup_rules

device_cgroup_rules defines a list of device cgroup rules for this container. The format is the same format the Linux kernel specifies in the Control Groups Device Whitelist Controller .

devices defines a list of device mappings for created containers in the form of HOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS] .

dns defines custom DNS servers to set on the container network interface configuration. It can be a single value or a list.

dns_opt list custom DNS options to be passed to the container’s DNS resolver ( /etc/resolv.conf file on Linux).

dns_search defines custom DNS search domains to set on container network interface configuration. It can be a single value or a list.

domainname declares a custom domain name to use for the service container. It must be a valid RFC 1123 hostname.

driver_opts

driver_opts specifies a list of options as key-value pairs to pass to the driver. These options are driver-dependent.

Consult the network drivers documentation for more information.

entrypoint declares the default entrypoint for the service container. This overrides the ENTRYPOINT instruction from the service's Dockerfile.

If entrypoint is non-null, Compose ignores any default command from the image, for example the CMD instruction in the Dockerfile.

See also command to set or override the default command to be executed by the entrypoint process.

In its short form, the value can be defined as a string:

Alternatively, the value can also be a list, in a manner similar to the Dockerfile :

If the value is null , the default entrypoint from the image is used.

If the value is [] (empty list) or '' (empty string), the default entrypoint declared by the image is ignored, i.e. overridden to be empty.

The env_file attribute is used to specify one or more files that contain environment variables to be passed to the containers.

env_file can also be a list. The files in the list are processed from the top down. For the same variable specified in two env files, the value from the last file in the list stands.

List elements can also be declared as a mapping, which then lets you set an additional attribute required . This defaults to true . When required is set to false and the .env file is missing, Compose silently ignores the entry.

required attribute is available with Docker Compose version 2.24.0 or later.

Relative path are resolved from the Compose file's parent folder. As absolute paths prevent the Compose file from being portable, Compose warns you when such a path is used to set env_file .

Environment variables declared in the environment section override these values. This holds true even if those values are empty or undefined.

Env_file format

Each line in an .env file must be in VAR[=[VAL]] format. The following syntax rules apply:

• Lines beginning with # are processed as comments and ignored.
• Blank lines are ignored.
• Unquoted and double-quoted ( " ) values have Interpolation applied.
• VAR=VAL -> VAL
• VAR="VAL" -> VAL
• VAR='VAL' -> VAL
• VAR=VAL # comment -> VAL
• VAR=VAL# not a comment -> VAL# not a comment
• VAR="VAL # not a comment" -> VAL # not a comment
• VAR="VAL" # comment -> VAL
• VAR='$OTHER' -> $OTHER
• VAR='${OTHER}' -> ${OTHER}
• VAR='Let\'s go!' -> Let's go!
• VAR="{\"hello\": \"json\"}" -> {"hello": "json"}
• VAR="some\tvalue" -> some value
• VAR='some\tvalue' -> some\tvalue
• VAR=some\tvalue -> some\tvalue

VAL may be omitted, in such cases the variable value is an empty string. =VAL may be omitted, in such cases the variable is unset.

environment

The environment attribute defines environment variables set in the container. environment can use either an array or a map. Any boolean values; true, false, yes, no, should be enclosed in quotes to ensure they are not converted to True or False by the YAML parser.

Environment variables can be declared by a single key (no value to equals sign). In this case Compose relies on you to resolve the value. If the value is not resolved, the variable is unset and is removed from the service container environment.

Map syntax:

Array syntax:

When both env_file and environment are set for a service, values set by environment have precedence.

expose defines the (incoming) port or a range of ports that Compose exposes from the container. These ports must be accessible to linked services and should not be published to the host machine. Only the internal container ports can be specified.

Syntax is <portnum>/[<proto>] or <startport-endport>/[<proto>] for a port range. When not explicitly set, tcp protocol is used.

Note If the Dockerfile for the image already exposes ports, it is visible to other containers on the network even if expose is not set in your Compose file.

extends lets you share common configurations among different files, or even different projects entirely. With extends you can define a common set of service options in one place and refer to it from anywhere. You can refer to another Compose file and select a service you want to also use in your own application, with the ability to override some attributes for your own needs.

You can use extends on any service together with other configuration keys. The extends value must be a mapping defined with a required service and an optional file key.

• service : Defines the name of the service being referenced as a base, for example web or database .
• file : The location of a Compose configuration file defining that service.

When a service uses extends , it can also specify dependencies on other resources, an explicit volumes declaration for instance. However, it's important to note that extends does not automatically incorporate the target volume definition into the extending Compose file. Instead, you are responsible for ensuring that an equivalent resource exists for the service being extended to maintain consistency. Docker Compose verifies that a resource with the referenced ID is present within the Compose model.

Dependencies on other resources in an extends target can be:

• An explicit reference by volumes , networks , configs , secrets , links , volumes_from or depends_on
• A reference to another service using the service:{name} syntax in namespace declaration ( ipc , pid , network_mode )

Circular references with extends are not supported, Compose returns an error when one is detected.

Finding referenced service

file value can be:

• Not present. This indicates that another service within the same Compose file is being referenced.
• Relative path. This path is considered as relative to the location of the main Compose file.
• Absolute path.

A service denoted by service must be present in the identified referenced Compose file. Compose returns an error if:

• The service denoted by service is not found.
• The Compose file denoted by file is not found.

Merging service definitions

Two service definitions, the main one in the current Compose file and the referenced one specified by extends , are merged in the following way:

• Mappings: Keys in mappings of the main service definition override keys in mappings of the referenced service definition. Keys that aren't overridden are included as is.
• Sequences: Items are combined together into a new sequence. The order of elements is preserved with the referenced items coming first and main items after.
• Scalars: Keys in the main service definition take precedence over keys in the referenced one.

The following keys should be treated as mappings: annotations , build.args , build.labels , build.extra_hosts , deploy.labels , deploy.update_config , deploy.rollback_config , deploy.restart_policy , deploy.resources.limits , environment , healthcheck , labels , logging.options , sysctls , storage_opt , extra_hosts , ulimits .

One exception that applies to healthcheck is that the main mapping cannot specify disable: true unless the referenced mapping also specifies disable: true . Compose returns an error in this case.

For example, the input below:

Produces the following configuration for the cli service. The same output is produced if array syntax is used.

Items under blkio_config.device_read_bps , blkio_config.device_read_iops , blkio_config.device_write_bps , blkio_config.device_write_iops , devices and volumes are also treated as mappings where key is the target path inside the container.

Produces the following configuration for the cli service. Note that the mounted path now points to the new volume name and ro flag was applied.

If the referenced service definition contains extends mapping, the items under it are simply copied into the new merged definition. The merging process is then kicked off again until no extends keys are remaining.

Produces the following configuration for the cli service. Here, cli services gets user key from common service, which in turn gets this key from base service.

The following keys should be treated as sequences: cap_add , cap_drop , configs , deploy.placement.constraints , deploy.placement.preferences , deploy.reservations.generic_resources , device_cgroup_rules , expose , external_links , ports , secrets , security_opt . Any duplicates resulting from the merge are removed so that the sequence only contains unique elements.

Produces the following configuration for the cli service.

In case list syntax is used, the following keys should also be treated as sequences: dns , dns_search , env_file , tmpfs . Unlike sequence fields mentioned above, duplicates resulting from the merge are not removed.

Any other allowed keys in the service definition should be treated as scalars.

external_links

external_links link service containers to services managed outside of your Compose application. external_links define the name of an existing service to retrieve using the platform lookup mechanism. An alias of the form SERVICE:ALIAS can be specified.

extra_hosts

extra_hosts adds hostname mappings to the container network interface configuration ( /etc/hosts for Linux).

Short syntax uses plain strings in a list. Values must set hostname and IP address for additional hosts in the form of HOSTNAME=IP .

IPv6 addresses can be enclosed in square brackets, for example:

The separator = is preferred, but : can also be used. Introduced in Docker Compose version 2.24.1 . For example:

Alternatively, extra_hosts can be set as a mapping between hostname(s) and IP(s)

Compose creates a matching entry with the IP address and hostname in the container's network configuration, which means for Linux /etc/hosts get extra lines:

group_add specifies additional groups, by name or number, which the user inside the container must be a member of.

An example of where this is useful is when multiple containers (running as different users) need to all read or write the same file on a shared volume. That file can be owned by a group shared by all the containers, and specified in group_add .

Running id inside the created container must show that the user belongs to the mail group, which would not have been the case if group_add were not declared.

healthcheck

The healthcheck attribute declares a check that's run to determine whether or not the service containers are "healthy". It works in the same way, and has the same default values, as the HEALTHCHECK Dockerfile instruction set by the service's Docker image. Your Compose file can override the values set in the Dockerfile.

For more information on HEALTHCHECK , see the Dockerfile reference .

interval , timeout , start_period , and start_interval are specified as durations . Introduced in Docker Compose version 2.20.2

test defines the command Compose runs to check container health. It can be either a string or a list. If it's a list, the first item must be either NONE , CMD or CMD-SHELL . If it's a string, it's equivalent to specifying CMD-SHELL followed by that string.

Using CMD-SHELL runs the command configured as a string using the container's default shell ( /bin/sh for Linux). Both forms below are equivalent:

NONE disables the healthcheck, and is mostly useful to disable the Healthcheck Dockerfile instruction set by the service's Docker image. Alternatively, the healthcheck set by the image can be disabled by setting disable: true :

hostname declares a custom host name to use for the service container. It must be a valid RFC 1123 hostname.

image specifies the image to start the container from. image must follow the Open Container Specification addressable image format , as [<registry>/][<project>/]<image>[:<tag>|@<digest>] .

If the image does not exist on the platform, Compose attempts to pull it based on the pull_policy . If you are also using the Compose Build Specification , there are alternative options for controlling the precedence of pull over building the image from source, however pulling the image is the default behavior.

image may be omitted from a Compose file as long as a build section is declared. If you are not using the Compose Build Specification, Compose won't work if image is missing from the Compose file.

init runs an init process (PID 1) inside the container that forwards signals and reaps processes. Set this option to true to enable this feature for the service.

The init binary that is used is platform specific.

ipc configures the IPC isolation mode set by the service container.

• shareable : Gives the container its own private IPC namespace, with a possibility to share it with other containers.
• service:{name} : Makes the container join another container's ( shareable ) IPC namespace.

isolation specifies a container’s isolation technology. Supported values are platform specific.

labels add metadata to containers. You can use either an array or a map.

It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with those used by other software.

Compose creates containers with canonical labels:

• com.docker.compose.project set on all resources created by Compose to the user project name
• com.docker.compose.service set on service containers with service name as defined in the Compose file

The com.docker.compose label prefix is reserved. Specifying labels with this prefix in the Compose file results in a runtime error.

links defines a network link to containers in another service. Either specify both the service name and a link alias ( SERVICE:ALIAS ), or just the service name.

Containers for the linked service are reachable at a hostname identical to the alias, or the service name if no alias is specified.

Links are not required to enable services to communicate. When no specific network configuration is set, any service is able to reach any other service at that service’s name on the default network. If services do declare networks they are attached to, links does not override the network configuration and services not attached to a shared network are not be able to communicate. Compose doesn't warn you about a configuration mismatch.

Links also express implicit dependency between services in the same way as depends_on , so they determine the order of service startup.

logging defines the logging configuration for the service.

The driver name specifies a logging driver for the service's containers. The default and available values are platform specific. Driver specific options can be set with options as key-value pairs.

mac_address

Available with Docker Compose version 2.24.0 and later.

mac_address sets a MAC address for the service container.

Note Container runtimes might reject this value (ie. Docker Engine >= v25.0). In that case, you should use networks.mac_address instead.

mem_limit configures a limit on the amount of memory a container can allocate, set as a string expressing a byte value .

When set, mem_limit must be consistent with the limits.memory attribute in the Deploy Specification .

mem_reservation

mem_reservation configures a reservation on the amount of memory a container can allocate, set as a string expressing a byte value .

When set, mem_reservation must be consistent with the reservations.memory attribute in the Deploy Specification .

mem_swappiness

mem_swappiness defines as a percentage, a value between 0 and 100, for the host kernel to swap out anonymous memory pages used by a container.

• 0 : Turns off anonymous page swapping.
• 100 : Sets all anonymous pages as swappable.

The default value is platform specific.

memswap_limit

memswap_limit defines the amount of memory the container is allowed to swap to disk. This is a modifier attribute that only has meaning if memory is also set. Using swap lets the container write excess memory requirements to disk when the container has exhausted all the memory that is available to it. There is a performance penalty for applications that swap memory to disk often.

• If memswap_limit is set to a positive integer, then both memory and memswap_limit must be set. memswap_limit represents the total amount of memory and swap that can be used, and memory controls the amount used by non-swap memory. So if memory ="300m" and memswap_limit ="1g", the container can use 300m of memory and 700m (1g - 300m) swap.
• If memswap_limit is set to 0, the setting is ignored, and the value is treated as unset.
• If memswap_limit is set to the same value as memory , and memory is set to a positive integer, the container does not have access to swap.
• If memswap_limit is unset, and memory is set, the container can use as much swap as the memory setting, if the host container has swap memory configured. For instance, if memory ="300m" and memswap_limit is not set, the container can use 600m in total of memory and swap.
• If memswap_limit is explicitly set to -1, the container is allowed to use unlimited swap, up to the amount available on the host system.

network_mode

network_mode sets a service container's network mode.

• none : Turns off all container networking.
• host : Gives the container raw access to the host's network interface.
• service:{name} : Gives the containers access to the specified service only. For more information, see Container networks .

When set, the networks attribute is not allowed and Compose rejects any Compose file containing both attributes.

The networks attribute defines the networks that service containers are attached to, referencing entries under the networks top-level element. The networks attribute helps manage the networking aspects of containers, providing control over how services are segmented and interact within the Docker environment. This is used to specify which networks the containers for that service should connect to. This is important for defining how containers communicate with each other and externally.

For more information about the networks top-level element, see Networks .

aliases declares alternative hostnames for the service on the network. Other containers on the same network can use either the service name or an alias to connect to one of the service's containers.

Since aliases are network-scoped, the same service can have different aliases on different networks.

Note A network-wide alias can be shared by multiple containers, and even by multiple services. If it is, then exactly which container the name resolves to is not guaranteed.

In the following example, service frontend is able to reach the backend service at the hostname backend or database on the back-tier network. The service monitoring is able to reach same backend service at backend or mysql on the admin network.

ipv4_address, ipv6_address

Specify a static IP address for a service container when joining the network.

The corresponding network configuration in the top-level networks section must have an ipam attribute with subnet configurations covering each static address.

link_local_ips

link_local_ips specifies a list of link-local IPs. Link-local IPs are special IPs which belong to a well known subnet and are purely managed by the operator, usually dependent on the architecture where they are deployed.

mac_address sets the MAC address used by the service container when connecting to this particular network.

priority indicates in which order Compose connects the service’s containers to its networks. If unspecified, the default value is 0.

In the following example, the app service connects to app_net_1 first as it has the highest priority. It then connects to app_net_3 , then app_net_2 , which uses the default priority value of 0.

oom_kill_disable

If oom_kill_disable is set, Compose configures the platform so it won't kill the container in case of memory starvation.

oom_score_adj

oom_score_adj tunes the preference for containers to be killed by platform in case of memory starvation. Value must be within -1000,1000 range.

pid sets the PID mode for container created by Compose. Supported values are platform specific.

pids_limit tunes a container’s PIDs limit. Set to -1 for unlimited PIDs.

When set, pids_limit must be consistent with the pids attribute in the Deploy Specification .

platform defines the target platform the containers for the service run on. It uses the os[/arch[/variant]] syntax.

The values of os , arch , and variant must conform to the convention used by the OCI Image Spec .

Compose uses this attribute to determine which version of the image is pulled and/or on which platform the service’s build is performed.

The ports is used to define the port mappings between the host machine and the containers. This is crucial for allowing external access to services running inside containers. It can be defined using short syntax for simple port mapping or long syntax, which includes additional options like protocol type and network mode.

Note Port mapping must not be used with network_mode: host otherwise a runtime error occurs.

The short syntax is a colon-separated string to set the host IP, host port, and container port in the form:

[HOST:]CONTAINER[/PROTOCOL] where:

• HOST is [IP:](port | range)
• CONTAINER is port | range
• PROTOCOL to restrict port to specified protocol. tcp and udp values are defined by the Specification, Compose offers support for platform-specific protocol names.

If host IP is not set, it binds to all network interfaces. Ports can be either a single value or a range. Host and container must use equivalent ranges.

Either specify both ports ( HOST:CONTAINER ), or just the container port. In the latter case, the container runtime automatically allocates any unassigned port of the host.

HOST:CONTAINER should always be specified as a (quoted) string, to avoid conflicts with yaml base-60 float .

Note If Host IP mapping is not supported by a container engine, Compose rejects the Compose file and ignores the specified host IP.

The long form syntax allows the configuration of additional fields that can't be expressed in the short form.

• target : The container port
• published : The publicly exposed port. It is defined as a string and can be set as a range using syntax start-end . It means the actual port is assigned a remaining available port, within the set range.
• host_ip : The Host IP mapping, unspecified means all network interfaces ( 0.0.0.0 ).
• protocol : The port protocol ( tcp or udp ). Defaults to tcp .
• app_protocol : The application protocol (TCP/IP level 4 / OSI level 7) this port is used for. This is optional and can be used as a hint for Compose to offer richer behavior for protocols that it understands. Introduced in Docker Compose version 2.26.0 .
• mode : host : For publishing a host port on each node, or ingress for a port to be load balanced. Defaults to ingress .
• name : A human-readable name for the port, used to document it's usage within the service.

privileged configures the service container to run with elevated privileges. Support and actual impacts are platform specific.

profiles defines a list of named profiles for the service to be enabled under. If unassigned, the service is always started but if assigned, it is only started if the profile is activated.

If present, profiles follow the regex format of [a-zA-Z0-9][a-zA-Z0-9_.-]+ .

pull_policy

pull_policy defines the decisions Compose makes when it starts to pull images. Possible values are:

• always : Compose always pulls the image from the registry.
• never : Compose doesn't pull the image from a registry and relies on the platform cached image. If there is no cached image, a failure is reported.
• missing : Compose pulls the image only if it's not available in the platform cache. This is the default option if you are not also using the Compose Build Specification . if_not_present is considered an alias for this value for backward compatibility.
• build : Compose builds the image. Compose rebuilds the image if it's already present.

read_only configures the service container to be created with a read-only filesystem.

restart defines the policy that the platform applies on container termination.

• no : The default restart policy. It does not restart the container under any circumstances.
• always : The policy always restarts the container until its removal.
• on-failure[:max-retries] : The policy restarts the container if the exit code indicates an error. Optionally, limit the number of restart retries the Docker daemon attempts.
• unless-stopped : The policy restarts the container irrespective of the exit code but stops restarting when the service is stopped or removed.

You can find more detailed information on restart policies in the Restart Policies (--restart) section of the Docker run reference page.

runtime specifies which runtime to use for the service’s containers.

For example, runtime can be the name of an implementation of OCI Runtime Spec , such as "runc".

The default is runc . To use a different runtime, see Alternative runtimes .

scale specifies the default number of containers to deploy for this service. When both are set, scale must be consistent with the replicas attribute in the Deploy Specification .

The secrets attribute grants access to sensitive data defined by the secrets top-level element on a per-service basis. Services can be granted access to multiple secrets.

Two different syntax variants are supported; the short syntax and the long syntax. Long and short syntax for secrets may be used in the same Compose file.

Compose reports an error if the secret doesn't exist on the platform or isn't defined in the secrets top-level section of the Compose file.

Defining a secret in the top-level secrets must not imply granting any service access to it. Such grant must be explicit within service specification as secrets service element.

The short syntax variant only specifies the secret name. This grants the container access to the secret and mounts it as read-only to /run/secrets/<secret_name> within the container. The source name and destination mountpoint are both set to the secret name.

The following example uses the short syntax to grant the frontend service access to the server-certificate secret. The value of server-certificate is set to the contents of the file ./server.cert .

The long syntax provides more granularity in how the secret is created within the service's containers.

• source : The name of the secret as it exists on the platform.
• target : The name of the file to be mounted in /run/secrets/ in the service's task container, or absolute path of the file if an alternate location is required. Defaults to source if not specified.
• uid and gid : The numeric UID or GID that owns the file within /run/secrets/ in the service's task containers. Default value is USER running container.
• mode : The permissions for the file to be mounted in /run/secrets/ in the service's task containers, in octal notation. The default value is world-readable permissions (mode 0444 ). The writable bit must be ignored if set. The executable bit may be set.

The following example sets the name of the server-certificate secret file to server.cert within the container, sets the mode to 0440 (group-readable), and sets the user and group to 103 . The value of server-certificate is set to the contents of the file ./server.cert .

security_opt

security_opt overrides the default labeling scheme for each container.

For further default labeling schemes you can override, see Security configuration .

shm_size configures the size of the shared memory ( /dev/shm partition on Linux) allowed by the service container. It's specified as a byte value .

stdin_open configures a service's container to run with an allocated stdin. This is the same as running a container with the -i flag. For more information, see Keep STDIN open .

Supported values are true or false .

stop_grace_period

stop_grace_period specifies how long Compose must wait when attempting to stop a container if it doesn't handle SIGTERM (or whichever stop signal has been specified with stop_signal ), before sending SIGKILL. It's specified as a duration .

Default value is 10 seconds for the container to exit before sending SIGKILL.

stop_signal

stop_signal defines the signal that Compose uses to stop the service containers. If unset containers are stopped by Compose by sending SIGTERM .

storage_opt

storage_opt defines storage driver options for a service.

sysctls defines kernel parameters to set in the container. sysctls can use either an array or a map.

You can only use sysctls that are namespaced in the kernel. Docker does not support changing sysctls inside a container that also modify the host system. For an overview of supported sysctls, refer to configure namespaced kernel parameters (sysctls) at runtime .

tmpfs mounts a temporary file system inside the container. It can be a single value or a list.

tty configures a service's container to run with a TTY. This is the same as running a container with the -t or --tty flag. For more information, see Allocate a pseudo-TTY .

ulimits overrides the default ulimits for a container. It's specified either as an integer for a single limit or as mapping for soft/hard limits.

user overrides the user used to run the container process. The default is set by the image (i.e. Dockerfile USER ). If it's not set, then root .

userns_mode

userns_mode sets the user namespace for the service. Supported values are platform specific and may depend on platform configuration.

uts configures the UTS namespace mode set for the service container. When unspecified it is the runtime's decision to assign a UTS namespace, if supported. Available values are:

• 'host' : Results in the container using the same UTS namespace as the host.

The volumes attribute define mount host paths or named volumes that are accessible by service containers. You can use volumes to define multiple types of mounts; volume , bind , tmpfs , or npipe .

If the mount is a host path and is only used by a single service, it can be declared as part of the service definition. To reuse a volume across multiple services, a named volume must be declared in the volumes top-level element.

The following example shows a named volume ( db-data ) being used by the backend service, and a bind mount defined for a single service.

For more information about the volumes top-level element, see Volumes .

The short syntax uses a single string with colon-separated values to specify a volume mount ( VOLUME:CONTAINER_PATH ), or an access mode ( VOLUME:CONTAINER_PATH:ACCESS_MODE ).

• VOLUME : Can be either a host path on the platform hosting containers (bind mount) or a volume name.
• CONTAINER_PATH : The path in the container where the volume is mounted.
• rw : Read and write access. This is the default if none is specified.
• ro : Read-only access.
• z : SELinux option indicating that the bind mount host content is shared among multiple containers.
• Z : SELinux option indicating that the bind mount host content is private and unshared for other containers.

Note The SELinux re-labeling bind mount option is ignored on platforms without SELinux.

Note Relative host paths are only supported by Compose that deploy to a local container runtime. This is because the relative path is resolved from the Compose file’s parent directory which is only applicable in the local case. When Compose deploys to a non-local platform it rejects Compose files which use relative host paths with an error. To avoid ambiguities with named volumes, relative paths should always begin with . or .. .

• type : The mount type. Either volume , bind , tmpfs , npipe , or cluster
• source : The source of the mount, a path on the host for a bind mount, or the name of a volume defined in the top-level volumes key . Not applicable for a tmpfs mount.
• target : The path in the container where the volume is mounted.
• read_only : Flag to set the volume as read-only.
• propagation : The propagation mode used for the bind.
• create_host_path : Creates a directory at the source path on host if there is nothing present. Compose does nothing if there is something present at the path. This is automatically implied by short syntax for backward compatibility with docker-compose legacy.
• selinux : The SELinux re-labeling option z (shared) or Z (private)
• nocopy : Flag to disable copying of data from a container when a volume is created.
• subpath : Path inside a volume to mount instead of the volume root.
• size : The size for the tmpfs mount in bytes (either numeric or as bytes unit).
• mode : The file mode for the tmpfs mount as Unix permission bits as an octal number. Introduced in Docker Compose version 2.14.0 .
• consistency : The consistency requirements of the mount. Available values are platform specific.

Tip Working with large repositories or monorepos, or with virtual file systems that are no longer scaling with your codebase? Compose now takes advantage of Synchronized file shares and automatically creates file shares for bind mounts. Ensure you're signed in to Docker with a paid subscription and have enabled both Access experimental features and Manage Synchronized file shares with Compose in Docker Desktop's settings.

volumes_from

volumes_from mounts all of the volumes from another service or container. You can optionally specify read-only access ro or read-write rw . If no access level is specified, then read-write access is used.

You can also mount volumes from a container that is not managed by Compose by using the container: prefix.

working_dir

working_dir overrides the container's working directory which is specified by the image, for example Dockerfile's WORKDIR .

• Stack Overflow for Teams Where developers & technologists share private knowledge with coworkers
• Advertising & Talent Reach devs & technologists worldwide about your product, service or employer brand
• OverflowAI GenAI features for Teams
• OverflowAPI Train & fine-tune LLMs
• Labs The future of collective knowledge sharing
• About the company Visit the blog

Collectives™ on Stack Overflow

Find centralized, trusted content and collaborate around the technologies you use most.

Q&A for work

Connect and share knowledge within a single location that is structured and easy to search.

Get early access and see previews of new features.

Assigning TCP/IP Ports for In-House Application Use

I've written a WCF Service hosted by a Windows Service and it needs to listen on a known TCP/IP port. From what range can I safely allocate a port for use within my organization? That port will be embedded in the config files for the service and the clients that are consuming the service.

• 1 Duplicate of stackoverflow.com/questions/10476987/… –  matt2000 Commented Oct 21, 2014 at 12:30
• 2 This is a useful question, and other answerers make a good case that the "accepted" answer (by Jorge Ferreira) is incorrect or at least incomplete, as do the answers on the question of which this is a duplicate. Is it possible to "unaccept" that answer? –  Nat Kuhn Commented Dec 17, 2017 at 15:33
• Possible duplicate of Best TCP port number range for internal applications –  Mohammad Sadegh Commented Sep 6, 2018 at 5:36
• @MohammadSadegh - I don't think this question is a duplicate. I think it is an original . The other similar questions mentioned in the comments seem to have been asked after this question. matt2000 holds a position similar to yours but I disagree with him also. Best!!! –  Shawn Eary Commented Jul 8, 2021 at 22:25

6 Answers 6

Ports 0-1023 are the Well Known Ports and are assigned by IANA. These should only be used for the assigned protocols on public networks.

Ports 1024-65535 used to be called Registered Port Numbers (see rfc1700 ) but are now split into two areas (see rfc6335 ).

Ports 1024-49151 are the User Ports and are the ones to use for your own protocols.

Ports 49152-65535 are the Dynamic ports and should not be prescribed to a protocol.

The User Ports can be used for any protocol, but there are a finite number, so your use will clash with someone elses use on some network somewhere. IANA keep a record of registered port numbers (0-49151). If your protocol will be used on public networks then you need to look into registering it with IANA. If you are only using it within your own network then pick a port within this area (1024-49151) and check that port against the IANA register to make sure it isn't used by a protocol that could be used on your network. For private use it is probably better to pick a number that is assigned to a protocol you know won't be used than to choose one that is unassigned and so may be assigned in the future.

Don't use a port number within the Dynamic range. These ports are assigned by the operating system, dynamically and somewhat randomly. If you open a client connection (using bind() with port=0) you will be assigned an unused port from the dynamic range. There is no way to guarantee that a port in this range will always be free for your protocol.

• Exactly. If you choose a port in the Dynamic range for you application, listening with WCF for example, there is no guarantee that the port is always free and not used by any other application, as Windows could always use this port for another applications opening an outgoing connection. –  David Oliván Commented Mar 26, 2019 at 10:19
• Strictly in terms of the question that is being asked, this answer appears to be fundamentally wrong; the clue seeming to be the "assigned by IANA" comment (& "never assigned" hint at the right answer) within section # 6 of the RFC 6335 - < datatracker.ietf.org/doc/html/rfc6335#section-6 > - at least for ports that have not been submitted to/agreed as being accepted/'assigned' by IANA. –  DennisVM-D2i Commented Apr 7, 2023 at 11:24

Pick a port number from 49152 through 65535.

IANA publishes a list of currently assigned ports.

http://www.iana.org/assignments/port-numbers

The Dynamic and/or Private Ports are those from 49152 through 65535. This is the range from where you SHOULD pick a port for your in-house applications. Of course any port belonging to one of the unassigned ranges on the published list can be used. But be aware that by picking a port number from those unassigned ranges there is no guarantee whatsoever that the port you choose will not be a reserved port in the future.

UNASSIGNED PORT NUMBERS SHOULD NOT BE USED. THE IANA WILL ASSIGN THE NUMBER FOR THE PORT AFTER YOUR APPLICATION HAS BEEN APPROVED.

And make sure that the port number you pick is configurable as you stated:

That port will be embedded in the config files for the service and the clients that are consuming the service.

This will avoid headaches in case some other 3rd party you-cannot-touch software is using your port number. If that happens you just go ahead and change it on the configuration file and it just works.

• 26 On the other hand, application software MUST NOT assume that a specific port number in the Dynamic Ports range will always be available for communication at all times, and a port number in that range hence MUST NOT be used as a service identifier. RFC 6335 –  Bolu Commented Sep 22, 2014 at 10:39
• 14 Bolu is correct. Don't use a port number within the dynamic range . See my explanation elsewhere on this page. –  adrianwadey Commented Jul 1, 2016 at 9:04
• 3 Not wise. As the system might choose to assign the port you are using at any given moment. So your server might look as it working only to fail on a latter loading. –  rxantos Commented Sep 22, 2016 at 1:40
• 4 On the opposite, take a port already assigned to something you're sure won't ever get needed. For example, TCP 31457 is assigned to TetriNET, so it's a pretty sure bet (unless your business is multiplayer tetris). –  maaartinus Commented Aug 20, 2018 at 18:17
• 4 So I don't quite understand why this is still the chosen answer... –  Leonmax Commented Dec 21, 2019 at 21:31

Short answer: Avoid anything up to and including 1023, or over 49152, and test the chosen port against services on your network.

If you've taken the reasonable precautions that it appears you have (putting the port number in a config file), it shouldn't be an enormous disruption if you later discover a conflict.

But (so that I can add something to the other suggestions that have popped up while I've been typing) make sure that you make it easy to change! If it's in config files, make it obvious. Document it, and point it out in troubleshooting. It's the sort of thing that could go wrong, so make it easy to debug if it needs changing.

• 12 Wait, you're telling me to avoid ports above 49152, but the top answer says you should only pick ports 49152 and above. What? –  Camilo Martin Commented Feb 1, 2016 at 22:45
• 5 @CamiloMartin See also adrianwadey's answer. The top answer is sound advice for peer-to-peer applications (e.g. BitTorrent), since they tend to use dynamic ports anyway, often with some kind of discovery service; not so much for client-server applications, which need a reasonably stable port number – even if the port number is stored in a config file, you need to reconfigure the server and its clients whenever it changes. –  JuSTMOnIcAjUSTmONiCAJusTMoNICa Commented Jul 6, 2017 at 14:04

In addition to the other suggestions about picking a common application port, I'd suggest that you make the port configurable within your application. Hard-coded port numbers are a bad idea, particularly if you later find a port conflict with another application and need to change yours.

As a note remember to check those port by netstat /a /n to see if its using by other application or not. I find out vista used the 49152 .... for some application level reason. Basically, because most of the system level listener does not implement port sharing its much safe to use the those ports which are not used at all.

Here is a good list of common application ports . Make your own choice in an empty slot. Maybe you should also scan your network for any in-house special application.

Typically high numbers port are available and I would suggest them but they could be blocked by firewalls.

• 3 the link is broken. Please fix –  German Capuano Commented Jun 16, 2017 at 14:16

Your Answer

Reminder: Answers generated by artificial intelligence tools are not allowed on Stack Overflow. Learn more

Sign up or log in

Post as a guest.

Required, but never shown

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy .

Not the answer you're looking for? Browse other questions tagged tcp or ask your own question .

• The Overflow Blog
• Where does Postgres fit in a world of GenAI and vector databases?
• Mobile Observability: monitoring performance through cracked screens, old...
• Featured on Meta
• Announcing a change to the data-dump process
• Bringing clarity to status tag usage on meta sites
• What does a new user need in a homepage experience on Stack Overflow?
• Staging Ground Reviewer Motivation
• Feedback requested: How do you use tag hover descriptions for curating and do...

Hot Network Questions

• Is 3 ohm resistance value of a PCB fuse reasonable?
• A short story about a boy who was the son of a "normal" woman and a vaguely human denizen of the deep
• Is the spectrum of Hawking radiation identical to that of thermal radiation?
• Which hash algorithms support binary input of arbitrary bit length?
• How did Oswald Mosley escape treason charges?
• Can you give me an example of an implicit use of Godel's Completeness Theorem, say for example in group theory?
• magnetic boots inverted
• How can I draw intersection of a sphere and a plane?
• How to disable Google Lens in search when using Google Chrome?
• Stuck on Sokoban
• What happens when touching a piece which cannot make a legal move?
• 1960s Stylesheet/Format for working Physics problems
• Does the order of ingredients while cooking matter to an extent that it changes the overall taste of the food?
• Encode a VarInt
• What is the purpose of these 33-ohm series resistors on the RMII side of the LAN8742A?
• If Starliner returns safely on autopilot, can this still prove that it's safe? Could it be launched back up to the ISS again to complete it's mission?
• Ubuntu showing black screen with terminal after attempt to update
• Cannot open and HTML file stored on RAM-disk with a browser
• Coding exercise to represent an integer as words using python
• Journal keeps messing with my proof
• Can unlimited Duration spells be Dismissed?
• Where to donate foreign-language academic books?
• Do the amplitude and frequency of gravitational waves emitted by binary stars change as the stars get closer together?
• Where does the energy in ion propulsion come from?